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Preface 


This publication describes the Virtual Machine/System Product (VM/SP) 
System Product Interpreter (hereafter referred to as the interpreter) and the 
Restructured Extended eXecutor language (sometimes abbreviated REXX). 
Descriptions include use and syntax of the language, and explain how the 
interpreter “interprets” the Restructured Extended Executor language as a 
program is executing. 

Two manuals are available for people who intend to learn the Restructured 
Extended Executor language: 

• The VM/SP System Product Interpreter User*s Guide , SC24-5238, is more 
suitable for beginners, and programmers who have not used a 
“structured” language before. 

• The book you are now reading is more suitable for experienced 
programmers, particularly those who have used another high level 
language (for example, PL/I, Algol or Pascal). 

However, all users should use this book as a reference manual. 

For ease of reference, the material in this book is arranged in chapters: 

1. Introduction and General Concepts 

2. Instructions (in alphabetical order) 

3. Functions (in alphabetical order) 

4. Debug Aids 

5. Parsing (a method of dividing strings of words, such as command lines) 

6. Numerics and Arithmetic 

7. Reserved Keywords and Special Variables 

8. Some Useful CMS Commands 

9. System Interfaces. 


Preface iii 



There are four appendixes covering: 

• Performance 

• Example of a Function Package 

• Error Numbers and Messages 

• The System Product Interpreter in the GCS Environment. 
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Part 1: Introduction and General Concepts 


Brief Description of the Restructured Extended Executor Language 

The Restructured Extended Executor (REXX) language is a language 
particularly suitable for: 

• Command procedures (EXECs) 

• User defined XEDIT subcommands 

• Prototyping 

• Personal computing. 

It is a general purpose, high-level language not unlike PL/I. REXX has the 
usual “structured programming” instructions - IF, SELECT, DO WHILE, 
LEAVE and so on - and a number of useful built-in functions. 

No restrictions are imposed by the language on program format. There can 
be more than one clause on a line or a single clause can occupy more than 
one line. Indentation is allowed. Programs can, therefore, be coded in a 
format that emphasizes their structure, making them easier to read. 

There is no limit to the length of the values of variables, so long as all 
variables fit into the storage available. Symbols (variable names) are 
limited to a length of 250 characters. 

Compound symbols, such as 

NAME.X.Y 

(where X and Y can be the names of variables) may be used for constructing 
arrays and for other purposes. 

REXX programs normally have a filetype of EXEC; such files may contain 
CP and CMS commands. Similarly, REXX programs with a filetype of 
XEDIT may contain XEDIT subcommands. 

REXX programs are executed by an interpreter. That is, the program is 
executed line-by-line and word-by-word, without first being translated to 
another form (compiled). The advantage of this to the user is that if the 
program fails with a syntax error of some kind, the point of failure is 
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clearly indicated; usually, it will not take long to understand the difficulty 
and make a correction. 


Where to Find More Information 

This is the Reference Manual. Reference information is also available in a 
convenient summary (card) form, the VM/SP System Product Interpreter 
Language Reference Summary . 

You can find useful information in the VM/SP System Product Interpreter 
User’s Guide and through the on-line HELP facility available with VM/SP. 
For any program written in the Restructured Extended Executor (REXX) 
language, you can get information on how the interpreter interprets the 
program or a particular instruction by using the REXX instruction, 
TRACE. 


Structure and General Syntax 

Programs written in the Restructured Extended Executor (REXX) language 
must start with a comment (which distinguishes them from CMS EXEC and 
EXEC 2 language programs). 

A REXX program is built from a series of clauses that are composed of: 
zero or more blanks (which are ignored); a sequence of tokens (see below); 
zero or more blanks (again ignored); and a semicolon (;) delimiter that may 
be implied by line-end, certain keywords, or the colon (:), if it follows a 
single symbol. Each clause is scanned from left to right before execution, 
and the tokens composing it are identified. Instruction keywords are 
recognized at this stage, comments are removed, and multiple blanks 
(except within strings) are converted to single blanks. Blanks adjacent to 
special characters (including operators, see page 5) are also removed. 


Tokens 


The language is composed of tokens (of any length, up to an 
implementation restricted maximum) that are separated by blanks or by the 
nature of the tokens themselves. The classes of tokens are: 

Comments: 

any sequence of characters (on one or more lines) that are 
delimited by /* and */. Logically, comments may contain other 
comments, as long as each begins and ends with the necessary 
delimiters. Comments may be written anywhere in a program. 
Logically, they are ignored by the interpreter (and hence may be 
of any length), but they do act as separators. See 
Appendix A, “Performance Considerations” on page 167. 

/* This is a valid comment */ 
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Strings: 

a sequence including any characters and delimited by the single 
quote (') or the double quote ("). Use two consecutive double 
quotes ("") to represent a " character within a string delimited 
by double quotes. Similarly, use two consecutive single quotes 
(* 1 ) to represent a 1 character within a string delimited by 
single quotes. A string is a literal constant and its contents are 
never modified when it is interpreted. A string with no 
characters (that is, a string of length 0) is called a null string. 

These are valid strings: 

' Fred' 

"Don't Panic l" 

'You shouldn't* /* Same as "You shouldn't" * 

Implementation maximum: A literal string may contain up to 
250 characters. (But note that the length of computed results is 
limited only by the amount of storage available.) 

Note that if followed immediately by a (, the string is considered 
to be a name of a function. Or, if followed immediately by an X, 
it is considered to be a hexadecimal-defined string. 

Hexadecimal Strings: 

any sequence of zero or more hexadecimal digits (0-9, a-f, 

A-F), optionally separated by blanks, delimited by single or 
double quotes and immediately followed by the character x or X 
(The X may not be part of a longer symbol.) A single leading 0 is 
added, if necessary, at the front of the string to make an even 
number of hexadecimal digits, which then represent a character 
string constant formed by packing the hexadecimal codes given. 
The blanks, which may only be present at byte boundaries (and 
not at the beginning or end of the string), are to aid readability. 
They are ignored. 

These are valid hexadecimal strings: 

'ABCD'x 
"Id ec f8"X 
"1 d8"x 

Implementation maximum: The packed length of a 
hexadecimal string may not exceed 250 bytes. 


Symbols: 

groups of any EBCDIC characters, selected from the alphabetic 
and numeric characters (A-Z, a-z, 0-9) and/or from the 
characters @#$C.! ? and underscore, are called symbols. Any 
lowercase alphabetic character in a symbol is translated to 
uppercase. 
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These are valid symbols: 

Fred 

Albert.Hall 
HI! 

A symbol may be a label (see page 11) or a REXX keyword (see 
page 143). A symbol may be assigned a value. Valid symbols 
may not begin with a number or period. If it has not been 
assigned a value, its value is the characters of the symbol itself, 
translated to uppercase. 

Implementation maximum: A symbol may consist of up to 250 
characters. (But note that its value, if it is a variable, is limited 
only by the amount of storage available). 


Numbers: 

These are character strings consisting of one or more decimal 
digits optionally prefixed by a plus or minus sign, and optionally 
including a single period (.) that represents a decimal point. A 
number may also have a power of ten suffixed in conventional 
exponential notation: an E (uppercase or lowercase) followed 
optionally by a plus or minus sign then followed by one or more 
decimal digits defining the power of ten. Whenever a character 
string is used as a number it is possible that rounding will occur, 
to a precision specified by the NUMERIC DIGITS instruction 
(default nine digits). See pages 133-142 for a full definition of 
numbers. 

Numbers may have leading blanks (before and/or after the sign, 
if any) and may have trailing blanks. Embedded blanks are not 
permitted. Note that a symbol (see above) may be a number and 
so may a string constant. A number cannot be the name of a 
variable. 

These are valid numbers: 

12 

-17.9 
127.0650 
73e+128 
' + 7.9E5 ' 

A whole number is a number that has a zero (or no) decimal 
part, and that would not normally be expressed by the interpreter 
in exponential notation. That is, it has no more digits before the 
decimal point than the current setting of NUMERIC DIGITS 
(the default is 9). 

Implementation maximum: The exponent of a number 
expressed in exponential notation may have up to nine digits 
only. 
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Operators: 

The special characters: + -/ %* | & = -i>< and the 
sequences >= <= -i> -i< n= /= >< <> == -i== 

/== // && || ** (which may have embedded blanks) are 

operator tokens (see page 7). One or more blank character(s), 
where they occur in expressions but are not adjacent to another 
operator, also act as an operator. 

Special Characters: 

The characters , ; : ) ( together with the individual 
characters from the operators have special significance when 
found outside of strings. All these characters constitute the set 
of “special” characters. They all act as token delimiters, and 
blanks adjacent to any of these are removed, with the exception 
that a blank adjacent to the outside of a parenthesis is only 
deleted if it is also adjacent to another special character. 

For example the clause: 

'REPEAT* B + 3; 

is composed of six tokens - a string (' REPEAT 1 ), a blank operator, a symbol 
(B, which may have a value), an operator (+), a second symbol (3, which is a 
number and a symbol), and a delimiter (;). The blanks between the B and 
the + and between the + and the 3 are removed. However, one of the 
blanks between the REPEAT and the B remains as an operator. Thus, this is 
treated as though it were written: 

'REPEAT' B+3; 

Implementation maximum: During parsing of a clause, the internal form 
of a clause (which is approximately the same length as the visible form, 
except that extra blanks and comments are removed) may not exceed 500 
characters. Note that this does not limit in any way the length of data that 
can be manipulated, which is dependent upon the amount of storage 
(memory) available to the interpreter. 


Implied Semicolons and Continuations 

The end of a line marks the end of a clause (that is, a semicolon is implied), 
except in the following cases: 

• The line ends in the middle of a string 

• The line ends in the middle of a comment. 

If the line does not end in the middle of a string or comment and the last 
non-comment token was a comma, then it is not considered the end of the 
clause. The comma is functionally replaced by a blank, and hence acts as a 
continuation character. Note that the comma remains in execution 
traces. 
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This means that semicolons need only be included when there is more than 
one clause on a line. 

Notes: 

1. Semicolons are added automatically after colons (when following a 
single symbol) and after certain keywords when in the correct context. 
The keywords that may have this effect are: ELSE, OTHERWISE, and 
THEN. These special cases reduce typographical errors significantly. 

2. The two characters that indicate the beginning of a comment, 

should not be split by a line-end since they could not then be recognized 
correctly; an implied semicolon would be added. Similarly, the two 
characters indicating the end of a comment, should not be split. 
The two characters forming a double quote within a string are also 
subject to this line-end ruling. 


Expressions and Operators 


Expressions 


Many clauses may include expressions which can consist of terms (strings, 
symbols, or function calls), interspersed with operators and parentheses. 

Terms may be: 

• Strings (delimited by quotes), which are literal constants 

• Symbols (no quotes), which are translated to uppercase. Those that do 
not begin with a digit or a period may be the name of a variable, in 
which case they are replaced by the value of that variable as soon as 
they are needed during evaluation. Otherwise they are treated as a 
literal string. A symbol may also be compound. See page 13. 

• Function calls, which are of the form: 

symbol([expression[, ...]]) or string([expression[, ...] 

See page 69. 

Evaluation of an expression is left to right, modified by parentheses and by 
operator precedence in the usual “algebraic” manner (see below). 

Expressions are always wholly evaluated, unless an error occurs during 
evaluation. 

All data is in the form of “typeless” character strings, (typeless because it is 
not - as in some other languages - of a particular declared type, such as 
Binary, Hexadecimal, Array, etc.). Consequently, the result of evaluating 
any expression is itself a character string. All terms and results may be the 
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null string (a string of length 0). Note that the REXX language imposes no 
restriction on the maximum length of results, but there is usually some 
practical limitation dependent upon the amount of storage available to the 
interpreter. 


Operators 


Each operator (except for the prefix operators) acts on two terms, which 
may be symbols, strings, function calls, intermediate results, or 
subexpressions in parentheses. Each prefix operator acts on the term or 
subexpression that follows it. There are four types of operators: 


String Concatenation 


The concatenation operators are used to combine two strings to form one 
string. The combination may occur with or without an intervening blank: 

(blank) Concatenate terms with one blank in between 

11 Concatenate without an intervening blank 

(abuttal) Concatenate without an intervening blank 

Concatenation without a blank may be forced by using the || operator, but 
it is useful to know that if a string and a symbol are abutted, they will be 
concatenated. 

Example: 

If the variable FRED had the value 37.4, then Fred"%" would evaluate to 
37.4% 


Arithmetic 

Character strings that are valid numbers (see above) may be combined 
using the arithmetic operators: 

+ Add 

Subtract 

* Multiply 

/ Divide 

% Divide and return the integer part of the result 

// Divide and return the remainder (not modulo, since the result 

may be negative) 

** Raise a number to a whole-number power 
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Prefix - Negate the following term (must be numeric) 

Prefix + Take following term (must be numeric) as is. 

See the section “Part 6: Numerics and Arithmetic” on page 133 for details 
of accuracy, the format of valid numbers, and the combination rules for 
arithmetic. Note that if an arithmetic result is shown in exponential 
notation, it is likely that rounding has occurred. 


Comparative 


The comparative operators return the value 1 if the result of the 
comparison is true, or 0 otherwise. 

The “ = = ”, “—| = = ”, and “/ = = ” operators test for an exact match between 
two strings. In this case, the two strings must be identical before they are 
considered equal. 

For all the other comparison operators, if both terms involved are numeric, 
a numeric comparison (in which leading zeros are ignored, etc.) is effected; 
otherwise, both terms are treated as character strings (leading and trailing 
blanks are ignored, and then the shorter string is padded with blanks on 
the right). 

= = True if terms are exactly equal (identical) 

= True if the terms are equal (numerically or when padded, etc.) 

= = True if the terms are NOT exactly equal (inverse of = =) 

/= = True if the terms are NOT exactly equal (inverse of = = ) 

~i = Not equal (inverse of -) 

/= Not equal (inverse of =) 

> Greater than 

< Less than 

> < Greater than or less than (same as Not equal) 

< > Greater than or less than (same as Not equal) 

> = Greater than or equal to 

< Not less than 

< = Less than or equal to 

~i > Not greater than 
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Logical (Boolean) 


A character string is taken to have the value “false” if it is 0, and “true” if 
it is a 1. The logical operators take one or two such values (values other 
than 0 or 1 are not allowed) and return 0 or 1 as appropriate: 

& AND 

Returns 1 if both terms are true. 

| Inclusive OR 

Returns 1 if either term is true. 

&& Exclusive OR 

Returns 1 if either (but not both) is true. 

Prefix “i Logical NOT 

Negates; 1 becomes 0 and vice-versa. 


Operator Priorities 

Expression evaluation is from left to right; this is modified by parentheses 
and by operator precedence: 

• When parentheses are encountered, the expression in parentheses is 
evaluated first. 

• When the sequence: 

terml operatorl term2 operator2 term3 ... 

is encountered, and operator2 has a higher precedence that operatorl, 
the expression (term2 operator2 term3 ... ) is evaluated first, applying 
the same rule repeatedly as necessary. 

Note, however, that individual terms are evaluated from left to right in 
the expression (that is, as soon as they are encountered). It is only the 
order of operations that is affected by the precedence rules. 

For example, * (multiply) has a higher priority than + (add), so 3+2*5 will 
evaluate to 13 (rather than the 25 that would result if strict left to right 
evaluation occurred). 

The order of precedence of the operators is (highest at the top): 


-1 - + 

(prefix operators) 

** 

(exponentiation) 

* / % // 

(multiply and divide) 

+ - 

(add and subtract) 
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""II (abuttal) 

= > < 

= = - 1 * < > 

> < > = < = 

““I > -|< / = 


(concatenation with/without blank) 
(comparison operators) 


& 


(and) 


| && (or, exclusive or) 

Examples: 


Suppose that the following symbols represent variables; with values as 
shown: 


A has the value 1 3' 

DAY has the value ' Monday' 


Then: 


A+5 

-> 

•8' 




A-4*2 

-> 

•-5' 




A/2 

-> 

'1.5' 




0.5**2 

~> 

•0.25' 




(A+l)>7 

-> 

'O' 

/* that 

is. False 

V 

i • — » • 

-> 

•1* 

/* that 

is. True 

V 

i i == i i 

-> 

'O' 

/* that 

is. False 

V 

i i i • 

-> 

*1' 

/* that 

is. True 

*/ 

(A+l)*3*12 

-> 

'1' 

/* that 

is, True 

V 

Today is Day 
'If it is* day 

-> 

•TODAY 

IS Monday' 
is Monday' 



-> 

'If it 



Substr(Day,2,3) 

'! 1 xxx'!' 

-> 

'ond' 

/* Substr is a 

t function 

V 

-> 

' ! XXX! ' 





Note: The REXX order of precedence usually causes no difficulty, as it is 
the same as in conventional algebra and other computer languages. There 
is one exception, the prefix minus operator has a higher priority than the 
exponential operator. Thus: 

-3**2 -> 9 /* not -9 */ 

-(2+1)**2 -> 9 /* not -9 */ 
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Clauses 

The clauses may be subdivided into five types: 

Null clauses 

A clause consisting only of blanks and/or comments is completely ignored 
(except that if it includes a comment it will be traced, if appropriate). 

Note: A null clause is not an instruction, so (for example) putting an extra 
semicolon after the THEN or ELSE in an IF instruction is not equivalent 
to putting a dummy instruction (as it would be in PL/I). The NOP 
instruction is provided for this purpose. 

Labels 

A label is a clause that consists of a single symbol followed by a colon. 

The colon acts as an implicit clause terminator, so no semicolon is required. 
Labels are used to identify the targets of CALL instructions, SIGNAL 
instructions, and internal function calls. They may be traced selectively to 
aid debugging. 

Any number of successive clauses may be labels, so permitting multiple 
labels before another type of clause. 

Assignments 

Assignments are single clauses with the form symbol = expression. An 
assignment gives a variable a (new) value. 

Instructions 


An instruction is one or more clauses, the first of which starts with a 
keyword that identifies the instruction. These control the external 
interfaces, the flow of control, etc. Some instructions can include other 
(nested) instructions. In this example, the DO construct (DO, the group of 
instructions that follow it, and its associated END keyword) is considered a 
single instruction. 

DO 

instruction 

instruction 

instruction 

END 
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Commands 

Commands are single clauses consisting of just an expression. The 
expression is evaluated and passed as a command string to some external 
environment. 


Assignments 


A variable is an object whose value may be changed during the course of 
execution of a REXX program. The process of changing the value of a 
variable is called assigning a new value to it. The value of a variable is a 
single character string, of any length, that may contain any characters. 

Variables may be assigned a new value by the ARG, PARSE, or PULL 
instructions, but the most common way of changing the value of a variable 
is the assignment instruction itself. Any clause of the form: 

symbol=[expression]? 

is taken to be an assignment. The result of expression becomes the new 
value of the variable named by the symbol to the left of the equal sign. If 
expression is not given, the variable is set to the null string. 

Example: 

/* Next line gives "FRED" the value "Frederic" */ 

Fred=* Frederic' 

The symbol naming the variable cannot begin with a digit (0-9) Or a period. 
(Without the restriction on the first character of a variable name, it would 
be possible to redefine a number; for example 3=4; would give a variable 
called 3 the value 4.) 

Symbols may be used in an expression even if they have not been assigned a 
value, since they have a defined value at all times. When unassigned, the 
defined value is the character(s) of the symbol itself, translated to 
uppercase. 

Example: 

/* If "Freda" has not yet been assigned a value , */ 

/* then next line gives "FRED" the value "FREDA" */ 
Fred=Freda 

Symbols may be subdivided into four classes: constant symbols, simple 
symbols, compound symbols, and stems. Simple symbols may be used for 
variables where the name corresponds to a single value. Compound 
symbols and stems are used for more complex collections of variables, such 
as arrays and lists. 
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Constant symbols 

A constant symbol starts with a digit (0-9) or a period. 

The value of a constant symbol cannot be changed, and it is simply the 
string consisting of the characters of the symbol (that is, with any 
alphabetic characters translated to uppercase). 

These are constant symbols: 

77 

827.53 

.12345 

12e5 /* Same as 12E5 */ 

3D 

Simple symbols 


A simple symbol does not contain any periods, and does not start with a 
digit (0-9). 

By default, its value is the characters of the symbol (that is, translated to 
uppercase). If the symbol has been used as the target of an assignment, it 
names a variable and its value is the value of that variable. 

These are simple symbols: 

FRED 

Whatagoodideal /* Same as WHATAGOODIDEA1 */ 

$12 


Compound symbols 


A compound symbol contains at least one period, which has characters on 
each side of it. It may not start with a digit or a period. 

The name begins with a stem (that part of the symbol up to and including 
the first period), which is followed by parts of the name (delimited by 
periods) that are constant symbols, simple symbols, or null. 

These are compound symbols: 

FRED.3 
Array.I.J 
AMESSY..One.2. 

Before the symbol is used, the values of any simple symbols (I, J, and One 
in the example) are substituted into the symbol, thus generating a new 
derived name. This derived name is then used just like a simple symbol. 
That is, its value is by default the derived name, or (if it has been used as 
the target of an assignment) its value is the value of the variable named by 
the derived name. 
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The substitution into the symbol that takes place permits arbitrary 
indexing (subscripting) of collections of variables that have a common stem. 
Note that the values substituted may contain any characters (including 
periods). Substitution is only done once. 

To summarize: the derived name of a compound variable that is referenced 
by the symbol 


s0.sl.s2. - .sn 


is given by 
d0.vl.v2. - ,vn 

where dO is the uppercase form of the symbol sO, and vl to vn are the 
values of the constant or simple symbols si through sn. Any of the 
symbols sl-sn may be null. The values vl-vn may also be null and may 
contain any characters (lowercase characters will not be translated to 
uppercase and blanks will not be removed). 

Compound symbols may be used to set up arrays and lists of variables, in 
which the subscript is not necessarily numeric, and thus offer great scope 
for the creative programmer. A useful application is to set up an array in 
which the subscripts are taken from the value of one or more variables, so 
effecting a form of associative memory (“content addressable”). 

Some examples follow in the form of a small extract from a REXX program: 


a=3 

/* assigns *3* 

to the 

variable *A* 

V 

b=4 


/* 

*4* 

to 

* B * 

*/ 

c='Fred' 

/* 

'Fred* 

to 

*C* 

V 

a.b= 

'Fred' 

/* 

* Fred * 

to 

* A. 4 * 

*/ 

a.fred=5 

/* 

*5* 

to 

* A.FRED * 

*/ 

a. c= 

* Bill 1 

/* 

* Bill* 

to 

*A.Fred* 

*/ 

c. c= 

a.fred 

/* 

*5* 

to 

*C.Fred* 

V 

x.a. 

b=*Annie* 

/* 

* Annie 

* to 

* X. 3.4 * 

*/ 

say 

a b c a.a 

a.b 

a, c 

c.a a 

.fred x. 

a.4 


/* will display the string: */ 

/* '34 Fred A.3 Fred Bill C.3 5 Annie* */ 

Implementation maximum: The length of a variable name, after 
substitution, may not exceed 250 characters. 


Stems 


A stem contains just one period, which is the last character. It may not 
start with a digit or a period. 

These are stems: 

FRED, 

A. 
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By default, the value of a stem is the characters of its symbol (that is, 
translated to uppercase). If the symbol has been assigned a value, it names 
a variable and its value is the value of that variable. 

Further, when a stem is used as the target of an assignment, all possible 
compound variables whose names begin with that stem are given the new 
value, whether they had a previous value or not. Following the assignment, 
a reference to any compound symbol with that stem returns the new value 
until another value is assigned to the stem or to the individual variable. 

For example: 

hole. = "empty" 
hole.9 = "full" 

say hole.l hole.mouse hole.9 
/* says "empty empty full" */ 

Thus a whole collection of variables may be given the same value. For 
example, 

total. = 0 

do until “i datatype(n,number) 

say "Enter an amount and a name:" 
pull amt name 

total.name = total.name + amt 
end 

Note: The value that has been assigned to the whole collection of variables 
can always be obtained by using the stem. However, this is not the same as 
using a compound variable whose derived name is the same as the stem. 

For example, 

total. = 0 
null = "" 

total.null = total.null + 5 

say total, total.null /* says "0 5" */ 

Collections of variables, referred to by their stem, can also be manipulated 
by the DROP and PROCEDURE instructions. DROP FRED . drops all 
variables with that stem (see page 36), and PROCEDURE EXPOSE FRED . 
exposes all possible variables with that stem (see page 49). 

Notes: 

1. When a variable is changed by the ARG, PARSE, or PULL 
instructions, the effect is identical to an assignment. A stem used in a 
parsing template therefore sets an entire collection of variables. 

2. Since an expression may include the operator =, and an instruction 
may consist purely of an expression (see next section), there would be a 
possible ambiguity which is resolved by the following rule: any clause 
that starts with a symbol and whose second token is = is an 
assignment, rather than an expression (or an instruction). This is not 
a restriction, since the clause may be executed as a command in several 
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ways, such as by putting a null string before the first name, or by 
enclosing the first part of the expression in parentheses. 

Similarly, if a programmer unintentionally uses a REXX keyword as the 
variable name in an assignment, this should not cause confusion - for 
example the clause: 

Address='10 Downing Street'; 

would be an assignment, not an ADDRESS instruction. 


Commands to the Host 


Environment 

The host system for the interpreter is assumed to include at least one 
active environment for executing commands. One of these is selected by 
default on entry to a REXX program. 

The environment so selected will depend on the caller; for example if a 
program is called from CMS, the default environment is CMS. If called 
from an editor that accepts subcommands from the interpreter, the default 
environment would be that editor. For a discussion of this mechanism see 
“Issuing Subcommands from Your Program” on page 20. 

The environment may be changed using the ADDRESS instruction. It may 
be inspected using the ADDRESS built-in function. 

Commands 


Executing commands using the currently addressed environment may be 
achieved using an instruction of the form: 

expression? 

The expression is evaluated, resulting in a character string (which may be 
the null string) which is then prepared as appropriate and submitted to the 
host. 

The host then executes the command (which may have side-effects such as 
altering REXX variables). It eventually returns control to the interpreter, 
after setting a return code. The interpreter places this return code in the 
REXX special variable RC. For example, if the host were CMS, the 
sequence: 

fn = "JACK"; ft = "RABBIT" 

STATE fn ft A1 
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would result in the string STATE JACK RABBIT A1 being submitted to 
CMS. Of course, the simpler expression: 

1 STATE JACK RABBIT A1 1 

would have the same effect in this case. 

On return, the return code would be placed in RC that would probably have 
the value ‘O’ if the file JACK RABBIT A1 existed, or ‘28’ if it did not. 

Note: Remember that the expression is evaluated before it is passed to the 
environment. Any part of the expression that is not to be evaluated should 
be written in quotes. 

Examples: 

erase listing /* not "multiplied by"! */ 

load "(" start 
a = any 

access 192 "b/a" /* not "divided by ANY" */ 

The CMS Environment 

When the environment selected is CMS (which is the default for EXECs), 
the command is invoked exactly as if it had been issued from the command 
line (but cleanup after the command has completed is different). See ‘‘Calls 
Originating from a Clause That Is an Expression” on page 151. The 
interpreter will create two parameter lists: 

• The result of the expression, tokenized and translated to uppercase, is 
placed in a Tokenized Parameter List. 

• The result of the expression, unchanged, is placed in an Extended 
Parameter List. 

The interpreter then asks CMS to execute the command. The interpreter 
uses the same search order used for a command entered from the CMS 
interactive command environment. The first token of the command is taken 
as the command name. As soon as the command name is found, the search 
stops and the command is executed. 

The search order is: 

1. Search for an EXEC with the specified command name: 

a. Search for an EXEC in storage. If an EXEC with this name is 
found, CMS determines whether the EXEC has a USER, SYSTEM, 
or SHARED attribute. If the EXEC has the USER or SYSTEM 
attribute, it is executed. 

If the EXEC has the SHARED attribute, the INSTSEG setting of the 
SET command is checked. When INSTSEG is ON, all accessed 

Part 1: Introduction and General Concepts 17 




Introduction 


a 


disks are searched and the access mode of the Installation 
Discontiguous Shared Segment (DCSS) is compared to the mode of 
an EXEC with the name that resides on disk. If the access mode of 
the DCSS is equal to or higher than the disk mode, the EXEC in the 
DCSS is executed. Otherwise, the EXEC on disk is executed. 

b. Search for a file with the specified command name and a filetype 
EXEC on any currently accessed disk. CMS uses the standard 
search order (A through Z.) The table of active (open) disk files is 
searched first. An open file may be used ahead of a file that resides 
on a disk earlier in the search order. 

2. Search for a translation or synonym for the command name. If found, 
search for an EXEC with the valid translation or synonym by repeating 
Step 1. (For a description of the translate tables, see the SET 
TRANSLATE command in the VM/SP CMS Command Reference. For a 
description of the synonym tables, see the SYNONYM command in the 
VM/SP CMS Command Reference.) 

3. Using an SVC 202, CMS now searches for: 

a. a command installed as a nucleus extension 

b. a transient module already loaded with the command name 

c. a nucleus resident command 

d. a MODULE. 

Note: For more information on using the CMS SVC 202, refer to the 
VM/SP CMS User’s Guide. The table of active (open) disk files is 
searched first. An open file may be used ahead of a file that resides on 
a disk earlier in the search order. 

4. Search for a translation or synonym of the specified command name. If 
found, search for a module with the valid translation or synonym by 
repeating Step 3. 

5. If the command name is not known to CMS (that is, all the above fails), 
it is changed to uppercase and the interpreter asks CMS to execute the 
command as a CP command. 

Note: If the command is passed to CP, it will be executed as if it had been 
entered from the CMS command line. (Specifically, if the password 
suppression facility is in use, a CP command that provides a password will 
be rejected. To issue such a command, use ADDRESS COMMAND CP 
cp_command.) Since EXECs are often used as “covers” or extensions to 
existing MODULES, there is one exception to this order. A command 
issued from within an EXEC will not implicitly invoke that same EXEC and 
hence cause a possible recursion loop. To make your EXEC call itself 
recursively, use the CALL instruction or the EXEC command. 
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To invoke a CP command explicitly, use the CMS command prefix CP. 

To illustrate these last two points, suppose your EXEC contains the clause: 
cp spool printer class s 

You may have a “cover” program, CP EXEC, which is intended to intercept 
all explicit CP commands. If such a program exists, it will be invoked. If 
not, the CP command SPOOL will be invoked. You would prefix your 
command with the word cp if you wanted to avoid invoking SPOOL EXEC 
or SPOOL MODULE. 

Notes: 

1. The searches for EXECs, translations, synonyms, and CP commands are 
all affected by the CMS SET command (IMPEX, ABBREV, IMPCP, and 
TRANSLATE options). The full search order given above assumes 
these are all ON. 

2. When the environment is CMS, the interpreter provides both a 
Tokenized Parameter List and an Extended Parameter List. For 
example, the sequence: 

f n=" Jack"; ft="Assemblersource" 

State fn ft A1 
Myexec fn ft A1 

would result in both a Tokenized Parameter List and an Extended 
Parameter List being built for each command and submitted to CMS. 
The STATE command would use the Tokenized Parameter List 

(STATE ) (JACK ) (ASSEMBLE) (A1 ) 

while MYEXEC (if it were a REXX EXEC) would use the Extended 
Parameter List 

(MYEXEC Jack Assemblersource Al) 

For full details of this assembler language interface, see page 149. 
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The COMMAND Environment 

If you wish to issue commands without the search for EXECs or CP 
commands, and without any translation of the parameter lists, (without any 
uppercasing of the tokenized parameter list) you may use the environment 
called COMMAND. Simply include the instruction ADDRESS COMMAND 
at the start of your EXEC (see page 25). Commands will be passed to CMS 
directly, using SVC 202, described on page 151. 

The COMMAND environment name is recommended for use in “system” 
EXECs that make heavy use of MODULES and nucleus functions. This 
makes these EXECs more predictable (commands cannot be usurped by user 
EXECs, and operations can be independent of the user's setting of IMPCP 
and IMPEX) and faster (the EXEC and first abbreviation searches are 
avoided). 

Note to EXEC 2 users: EXEC 2 issues commands in this way. 


Issuing Subcommands from Your Program 

A command being executed by CMS may accept subcommands. Usually, 
the command will provide its own command line, from which it takes 
subcommands entered by the user. But this can be extended so that the 
command will accept subcommands from a REXX program. 

A typical example is an editor. You can write a REXX program that issues 
editor subcommands, and run your program during an editing session. 

Your program can inspect the file being edited, issue subcommands to make 
changes, test return codes to check that the subcommands have been 
executed as you expected, and display messages to the user when 
appropriate. The user can invoke your program by entering its name on the 
editor's command line. 

The editor (or any other program that is designed to accept subcommands 
from the interpreter) will first create a subcommand entry point, naming 
the environment to which subcommands may be addressed, and then call 
your program. Programs that can issue subcommands are called macros. 
The REXX (and EXEC 2) interpreter have the convention that, unless 
instructed otherwise, they direct commands to a subcommand environment 
whose name is the filetype of the macro. Usually, editors name their 
subcommand entry point with their own name and claim that name as the 
filetype to be used for their macros. 

For example, the XEDIT editor sets up a subcommand environment named 
XEDIT, and the filetype for XEDIT macros is also XEDIT. 

The macro issues subcommands to the editor (for example, NEXT 4, or 
EXTRACT @ZONE). The editor “replies” with a return code (which the 
interpreter assigns to the special variable RC) and sometimes with further 
information, which may be assigned to other REXX variables. For example, 
a return code of 1 from NEXT 4 indicates that end-of-file has been reached; 
EXTRACT @ZONE assigns the current limits of the zone of XEDIT to the 
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REXX variables Z0NE.1 and ZONE.2. By testing RC and the other REXX 
variables, the macro has the ability to react appropriately, and the full 
flexibility of a programmable interface is available. 

The interpreter allows the default environment to be altered (between 
various subcommand environments or the host environment) using the 
ADDRESS instruction. 

Note: The SUBCOM function is used to create, query, or delete 
subcommand entry points. 

Only the query form of SUBCOM is a subcommand, in the sense that it can 
be issued from the terminal (or from a REXX program). The form of this 
subcommand is: 

SUBCOM name 

This yields a return code of 0 if name is currently defined as a subcommand 
environment name, or 1 if it is not. 

The create and delete functions of SUBCOM are described in the VM/SP 
CMS for System Programming. 
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Several of the more powerful features of the language (notably functions) 
reduce the number of instructions needed in the REXX language. 

In the following diagrams, symbols (words) in capitals denote keywords, 
other words (such as expression) denote a collection of symbols as defined 
above. Note however that the keywords are not case dependent: the 
symbols if If and iF would all invoke the instruction shown below as IF. 
Note also that most of the clause delimiters (;) shown may usually be 
omitted as they will be implied by the end of a line. 

The brackets [ and ] delimit optional parts of the instructions. 

As explained on page 11, an instruction is recognized only if its keyword is 
the first token in a clause, and if the second token is neither an = 
character (implying an assignment) nor a colon (implying a label). The 
keywords ELSE, END, OTHERWISE, THEN, and WHEN are recognized in 
the same situation. A syntax error will result if they are not in their 
correct position(s) in a DO, IF, or SELECT instruction. (The keyword 
THEN may also be recognized in the body of an IF or WHEN clause.) In 
other contexts, all these keywords are not reserved and may be used as 
labels or as the names of variables (though this is generally not 
recommended). 

Certain other keywords are reserved within the clauses of individual 
instructions. (For details, refer to the description of the instruction.) For a 
general discussion on reserved keywords, see page 143. 
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ADDRESS 


environment [expression ] 
[value] expression 


Where: 

environment 

is a single symbol or string, which is taken to be a constant. 

This instruction is used to effect a temporary or permanent change to the 
destination of command(s). The concept of alternative subcommand 
environments is described on page 20. 

To send a single command to a specified environment, an environment 
name followed by an expression is given, expression is evaluated, and the 
resulting command string is routed to environment . After execution of the 
command, environment will be set back to whatever it was before, thus 
giving a temporary change of destination for a single command. 

Example: 

Address CMS 'STATE PROFILE EXEC' 

If only environment is specified, a lasting change of destination occurs: 
all following commands (expressions not preceded by a REXX keyword) will 
be routed to the given command environment, until the next ADDRESS 
instruction is executed. The previously selected environment is saved. 

Example: 

address CMS 

'STATE PROFILE EXEC' 

if rc=0 then ’COPY PROFILE EXEC A TEMP = =' 
address XEDIT 

Similarly, the VALUE form may be used to make a lasting change to the 
environment - here expression (which may be just a variable name) is 
evaluated, and the result forms the name of the environment. The keyword 
VALUE may be omitted as long as expression starts with a special 
character (so that it cannot be mistaken for a symbol or string). 

Example: 

ADDRESS ('ENVIR 1 ||number) 

If no arguments are given, commands will be routed back to the 
environment that was selected before the previous lasting change of 
environment was made, and the current environment name is saved. 
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Repeated execution of just ADDRESS will therefore switch the command 
destination between two environments alternately. 

The two environment names are automatically saved across subroutine and 
internal function calls. See under the CALL instruction (page 28) for more 
details. 

The current ADDRESS setting may be retrieved using the ADDRESS 
built-in function, described on page 74. 

Note: In CMS, there are environment names that have special meaning. 
Following are three commonly used environment names: 

CMS This environment name, which is the default for EXECs, 

implies full command resolution just as provided in normal 
interactive command (terminal) mode. (See page 17 for 
details.) 

COMMAND This implies basic CMS SVC 202 command resolution. To 
invoke an EXEC, the word EXEC must prefix the command, 
and to issue a command to CP, the prefix CP must be used 
(see page 20). 

” (Null); same as COMMAND. Note that this is not the same 

as ADDRESS with no arguments, which will switch to the 
previous environment. 
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ARG 


ARG [template]; 


Where: 

template 

is a list of symbols separated by blanks and/or ‘patterns’. 

ARG is used to retrieve the argument strings provided to a program or 
internal routine and assign them to variables. It is just a short form of the 
instruction 

PARSE UPPER ARG [template]} 

Unless a subroutine or internal function is being executed, the input 
parameters to the program will be read, translated to uppercase, and then 
parsed into variables according to the rules described in the section on 
parsing (page 123). Use the PARSE ARG instruction if uppercase 
translation is not desired. 

If a subroutine or internal function is being executed, the data used will be 
the argument string(s) passed to the routine. 

The ARG (and PARSE ARG) instructions may be executed as often as 
desired (typically with different templates) and will always parse the same 
current input string(s). There are no restrictions on the length or content 
of the data parsed except those imposed by the caller. 

Example: 

/* String passed to FRED EXEC is "Easy Rider" */ 

Arg adjective noun . 

/* Now: "ADJECTIVE" contains * EASY * */ 

/* "NOUN" contains ‘RIDER* */ 

If more than one string is expected to be available to the program or 
routine, each may be selected in turn by using a comma in the parsing 
template. 

Example: 


/* function is invoked by FRED('data X',1,5) */ 
Fred: Arg string, numl, num2 

/* Now: "STRING" contains 'DATA X' */ 
/* "NUM1" contains *1' */ 
/* "NUM2" contains '5' */ 
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Notes: 

1. The argument string(s) to a REXX program or internal routine may also 
be retrieved or checked by using the ARG built-in function. See page 
75. 

2. The source of the data being interpreted is also made available on entry 
to the program. See the PARSE instruction (SOURCE option) on page 
47 for details. 

3. A string passed from CMS command level is restricted to 130 characters 
(including the name of the EXEC being invoked.) 

Note for CMS EXEC and EXEC 2 Users: Unlike CMS EXEC and EXEC 
2, the arguments passed to REXX programs can only be used after executing 
either the ARG or PARSE ARG instructions (or retrieving their value with 
the ARG built-in function). They are not immediately available in 
predefined variables as in the other languages. 
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CALL name [expression ] [, [expression ]} . .; 


CALL is used to invoke a routine. The routine may be an internal routine, 
an external routine or program, or a built-in function, name , given in the 
CALL instruction, must be a valid symbol, which is treated literally, or a 
string. If a string is used for name (that is, name is specified in quotes) the 
search for internal labels is bypassed, and only a built-in function or an 
external function will be invoked. Note that the names of built-in functions 
(and generally the names of external routines too) are in uppercase, and 
hence the name in the literal string should be in uppercase. 

The invoked routine may optionally return a result upon its completion, 
which is functionally identical to the clause: 

result=name([expression][,[expression]]...); 

where the variable RESULT will become uninitialized if no result is 
returned by the routine invoked. 

Up to ten expressions, separated by commas, may be specified. These are 
evaluated in order from left to right, and form the argument string(s) during 
execution of the routine. Any ARG or PARSE ARG instructions, or ARG 
built-in function in the called routine will access these strings, rather than 
those previously active in the calling program. Expressions may be omitted 
if desired. 

The CALL then causes a branch to the routine called name using exactly 
the same mechanism as function calls. The order in which these are 
searched for is described in the section on functions (page 69), but briefly is 
as follows: 

Internal routines: 

(unless the routine name is specified in quotes) These are 
sequences of instructions inside the same program, starting at 
the label that matches name in the CALL instruction. 

Built-in routines: 

These are routines built in to the interpreter for providing 
various functions. They always return a string containing the 
result of the function. (See page 73.) 

External routines: 

Users may write or make use of routines that are external to the 
interpreter and the calling program. An external routine may be 
written in any language, including REXX, which supports the 
system dependent interfaces used by the interpreter to invoke it - 
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see page 157 for details. A REXX program may be invoked as a 
subroutine by the CALL instruction, and in this case may be 
passed more than one argument string. These may be retrieved 
using the ARG or PARSE ARG instructions, or the ARG 
built-in function. 

During execution of an internal routine, all variables previously known are 
normally accessible. However, the PROCEDURE instruction may be used 
to set up a local variables environment to protect the subroutine and caller 
from each other. The EXPOSE option on the PROCEDURE instruction 
may further be used to expose selected variables to a routine. 

Calling an external program as a subroutine is similar to calling an 
internal routine. The external routine is however an implicit 
PROCEDURE in that all the caller's variables are always hidden, and the 
status of internal values (NUMERIC settings, etc.) start with their defaults 
(rather than inheriting those of the caller). 

When control reaches the internal routine, the line number of the CALL 
instruction is available in the variable SIGL (in the caller's variable 
environment). This may be used as a debug aid, as it is therefore possible 
to find out how control reached a routine. 

Eventually the subroutine should execute a RETURN instruction, and at 
that point control will return to the clause following the original CALL. If 
the RETURN instruction specified an expression, the variable RESULT 
will be set to the value of that expression. Otherwise, the variable 
RESULT is dropped (becomes uninitialized). 

Internal routines may include calls to other internal routines, including 
itself. 

Example: 

/* Recursive subroutine execution... */ 
arg x 

call factorial x 
say x’l = 1 result 
exit 

factorial: procedure 
arg n 

if n=0 then return 1 
call factorial n-1 
return result * n 

During internal subroutine (and function) execution, all important pieces of 
information are automatically saved and are then restored upon return 
from the routine. These are: 

• The status of DO-loops and other structures - Executing a SIGNAL 
while within a subroutine is “safe” in that DO-loops, etc.., that were 
active when the subroutine was called are not deactivated (but those 
currently active within the subroutine will be). 


/* calculate factorial by.. */ 
/* .. recursive invocation. */ 
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• Trace action - Once a subroutine is debugged, you may insert a 
TRACE Off at the beginning of it, and this will not affect the tracing of 
the caller. Conversely, if you only wish to debug a subroutine, you 
could insert a TRACE R at the start - tracing will automatically be 
restored to the conditions at entry (for example, “Off”) upon return. 
Similarly, ? (interactive debug) and l (command inhibition) are saved 
across routines. 

• NUMERIC settings (the DIGITS, FUZZ, and FORM of arithmetic 
operations, described on page 44) described in the NUMERIC 
instruction) are saved and are then restored on RETURN. A 
subroutine may therefore set the precision, etc., that it needs to use 
without affecting the caller. 

• ADDRESS settings (the current and secondary destinations for 
commands - see the ADDRESS instruction on page 24) are saved and 
are then restored on RETURN. 

• Exception conditions (SIGNAL ON condition) are saved and are then 
restored on RETURN. This means that SIGNAL ON and SIGNAL 
OFF may be used in a subroutine without affecting the conditions set 
up by the caller. 

• Elapsed time clocks - A subroutine inherits the elapsed time clock 
from its caller (see the TIME function on page 96), but since the time 
clock is saved across routine calls, a subroutine or internal function 
may independently restart and use the clock without affecting its caller. 
For the same reason, a clock started within an internal routine is not 
available to the caller. 

Implementation maximum: The total nesting of control structures, 

which includes internal routine calls, may not exceed a depth of 250. 
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DO 


DO 



Or, to present the instruction more generally: 



Where: 

repetitor 

is one of: 

name = expri [TO exprt] [BY exprb] [FOR exprf] 

FOREVER 

exprr 

conditional 

is one of: 

WHILE exprw 
UNTIL expru 

DO is used to group instructions together and optionally to execute them 
repetitively. During repetitive execution, a control variable (name) may be 
stepped through some range of values. 
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Syntax Notes: 


• exprr, expri , exprb , e*pr£, and exprf (if any are present) may be any 
expression that evaluates to a number, exprr and exprf are further 
restricted to result in a non-negative whole number. If necessary, the 
numbers will be rounded according to the setting of NUMERIC DIGITS. 

• exprw or expru (if present) may be any expression that evaluates to 1 or 

0 . 

• the TO, BY, and FOR phrases may be in any order, if used. 

• the instruction(s) may include constructs such as IF, SELECT, or the 
DO instruction itself. 

• the sub-keywords TO, BY, FOR, WHILE, and UNTIL are reserved 
within a DO instruction, in that they cannot name variables in the 
expression(s) but they may be used as the name of the control variable. 
FOREVER is similarly reserved, but only if it immediately follows the 
keyword DO. 

• exprb defaults to 1, if relevant. 


Simple DO Group 


If neither repetitor nor conditional is given, the construct merely groups a 
number of instructions together. These are executed once. Otherwise, the 
group of instructions is a repetitive DO loop, and they are executed 
according to the repetitor phrase, optionally modified by the conditional 
phrase. 

In the following example, the instructions are executed once. 

Example: 

/* The two instructions between DO and END will both */ 

/* be executed if A has the value 3. */ 

If a=3 then Do 

a=a+2 

Say 'Smile I 1 
End 


Simple Repetitive Loops 

If repetitor is not given or the repetitor is FOREVER, the group of 
instructions will nominally be executed “forever”; that is, until the 
condition is satisfied or a REXX instruction is executed that will end the 
loop (for example, LEAVE). 

Note: For a discussion on conditional phrases, see “Conditional Phrases 
(WHILE and UNTIL)” on page 34) 
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DO 


In the simple form of a repetitive loop, exprr is evaluated immediately (and 
must result in a non-negative whole number), and the loop is then executed 
that many times: 

Example: 

/* This displays "Hello" five times */ 

DO 5 

say 'Hello 1 
end 

Note that, similar to the distinction between a command and an 
assignment, if the first token of exprr is a symbol and the second token is 
an “ =,” the controlled form of repetitor will be expected. 


Controlled Repetitive Loops 

The controlled form specifies a control variable, name , which is assigned 
an initial value (the result of expri), The variable is then stepped (by 
adding the result of exprb , at the bottom of the loop) each time the group of 
instructions is executed. The group is executed repeatedly while the end 
condition (determined by the result of exprt) is met. If exprb is positive, the 
loop will be terminated when name is greater than exprt If negative, the 
loop will be terminated when name is less than exprt 


expri, exprt, and exprb must result in numbers. They are evaluated once 
only, before the loop begins and before the control variable is set to its 
initial value. The default value for exprb is 1. If exprt is not given, the loop 
will execute indefinitely unless some other condition terminates it. 


Example: 


Do 1=3 to -2 by -1 
say i 
end 


/* Would display: */ 

/* 3 */ 

/* 2 V 

/* 1 V 

/* o */ 

/* -1 V 

/* -2 V 


The numbers do not have to be whole numbers: 


Example: 

X=0.3 

Do Y=X to X+4 by 0.7 
say Y 
end 


/* 

Would display: 

*/ 

/* 

0.3 

*/ 

/* 

1.0 

*/ 

/* 

1.7 

*/ 

/* 

2.4 

V 

/* 

3.1 

*/ 

/* 

3.8 

V 


The control variable may be altered within the loop, and this may affect the 
iteration of the loop. Altering the value of the control variable is not 
normally considered good programming practice, though it may be 
appropriate in certain circumstances. 
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Note that the end condition is tested at the start of each iteration. It is 
therefore possible for the group of instructions to be skipped entirely if the 
end condition is met immediately. Note also that the control variable is 
referenced by name. If (for example) the compound name “A.I” was used for 
the control variable, altering "I” within the loop will cause a change in the 
control variable. 

The execution of a controlled loop may further be bounded by a FOR 
phrase. In this case, exprf must be given and must evaluate to a 
non-negative whole number. This acts just like the repetition count in a 
simple repetitive loop, and sets a limit to the number of iterations around 
the loop if no other condition terminates it. Like the TO and BY 
expressions, it is evaluated once only - when the DO instruction is first 
executed and before the control variable is given its initial value. Like the 
TO condition, the FOR condition is checked at the start of each iteration. 

Example: 

Do Y=0.3 to 4.3 by 0.7 for 3 /* Would display: */ 

say Y /* 0.3 */ 

end /* 1.0 */ 

/* 1.7 */ 

In a controlled loop, the symbol describing the control variable may be 
specified on the END clause. This symbol must match name in the DO 
clause (note that no substitution for compound variables is carried out); a 
syntax error will result if it does not. This enables the nesting of loops to 
be checked automatically, with minimal overhead. 

Example: 

Do K=1 to 10 

End k /* Checks that this is the END for K loop */ 

Note: The values taken by the control variable may be affected by the 
NUMERIC settings, since normal REXX arithmetic rules apply to the 
computation of stepping the control variable. 

Conditional Phrases (WHILE and UNTIL) 

Any of the forms of repetitor (none, FOREVER, simple, or controlled) may 
be followed by a conditional phrase, which may cause termination of the 
loop. If WHILE or UNTIL is specified, exprw or expru, respectively, is 
evaluated each time around the loop using the latest values of all variables 
(and must evaluate to either 0 or 1), and the group of instructions will be 
repeatedly executed either while the result is 1, or until the result is 1. 

For a WHILE loop, the condition is evaluated at the top of the group of 
instructions, and for an UNTIL loop the condition is evaluated at the 
bottom - before the control variable has been stepped. 
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Example: 

Do 1=1 to 10 by 2 until i>6 
say i 
end 

/* Would display: 1, 3, 5, 7 */ 

Note: The execution of repetitive loops may also be modified by using the 
LEAVE or ITERATE instructions. 



Figure 1. How a Typical DO Loop Is Executed 
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DROP 


DROP 


DROP name [name ] [name ]. . .; 


Where: 

name 

is a symbol, separated from any other names by one or more blanks. 

DROP is used to “unassign” variables; that is, to restore them to their 
original uninitialized state. 

Each variable specified will be dropped from the list of known variables. 
The variables are dropped in sequence from left to right. It is not an error 
to specify a name more than once, or to DROP a variable that is not 
known. If an EXPOSEd variable is named (see the PROCEDURE 
instruction), the variable itself in the older generation will be dropped. 

Example: 

j=4 

Drop a x. 3 x. j 

/* would reset the variables: "A", "X.3", and "X.4" */ 

/* so that reference to them returns their name. */ 

If a stem is specified (that is, a symbol that contains only one period, as the 
last character), all variables starting with that stem are dropped. 

Example: 

Drop x. 

/* would reset all with names starting with "X." */ 
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EXIT 


EXIT 


EXIT [ expression ]; 


EXIT is used to unconditionally leave a program, and optionally return a 
data string to the caller. The program is terminated immediately, even if an 
internal routine is currently being executed. If no internal routine is 
active, RETURN (see page 54) and EXIT have the same function. 

If expression is given, it is evaluated and the string resulting from the 
evaluation is then passed back to the caller when the program terminates. 

Example: 

j=3 

Exit j*4 

/* Would exit with the string 1 12 1 */ 

If expression is not given, no data is passed back to the caller. If the 
program was called as an external function, this will be detected as an error 
- either immediately (if RETURN was used), or on return to the caller (if 
EXIT was used). 

“Running off the end” of the program is always equivalent to the 
instruction EXIT, in that it terminates the whole program and returns no 
result string. 

Note: The interpreter does not distinguish between invocation as a 
command on the one hand, and invocation as a subroutine or function on 
the other. If in fact the program was invoked via the more primitive 
command interface (which only allows a numeric return code), an attempt 
is made to convert the returned value to a return code acceptable by the 
host. The returned string must then be a whole number whose value will fit 
in a S/370 register (that is, must be in the range -2**31 through 2**31-1). If 
the conversion fails, it is deemed to be a failure of the host interface and is 
thus not subject to trapping by SIGNAL ON SYNTAX. Note also that only 
the last five digits of the return code (four digits for a negative return code) 
will be displayed by the standard CMS ready message. 
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IF 


IF 



v_, 


IF expression [;] THEN[;] instruction 

[ ELSE [ ;] instruction ] 


The IF construct is used to conditionally execute an instruction or group of 
instructions - depending on the evaluation of the expression. 

The instruction after the THEN is executed only if the result of the 
evaluation was 1. If an ELSE was given, the instruction after the ELSE is 
executed only if the result of the evaluation was 0. 

Example: 

if answer='YES' then say 'OKI* 

else say 'Why not?' 

Remember that if the ELSE clause is on the same line as the last clause of 
the THEN part, you need a semicolon to terminate that clause. 

Example: 

if answer='YES' then say 'OK!'; else say 'Why not?' 

The ELSE binds to the nearest IF at the same level. 

Example: 

if answer='YES' then if name='FRED' then say 'OK, Fred.' 

else nop 

else say 'Why not?' 


Notes: 

1. instruction includes all the more complex constructs such as DO groups 
and SELECT groups, as well as the simpler ones and the IF instruction 
itself. A null clause is not an instruction; so putting an extra semicolon 
after the THEN or ELSE is not equivalent to putting a dummy 
instruction (as it would be in PL/I). The NOP instruction is provided 
for this purpose. 

2. A variable called THEN cannot be used within expression, because the 
keyword THEN is treated differently, in that it need not start a clause. 
This allows the expression on the IF clause to be terminated by the 
THEN, without a being required - were this not so, people used to 
other computer languages would experience considerable difficulties. 
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INTERPRET 


INTERPRET 


INTERPRET expression ; 


INTERPRET is used to execute instructions that have been built 
dynamically by evaluating expression . 

expression is evaluated, and will then be executed (interpreted) just as 
though the resulting string were a line inserted into the input file (and 
bracketed by a DO; and an END;). 

Any instructions (including INTERPRET instructions) are allowed, but 
note that constructions such as DO ... END and SELECT ... END must be 
complete. For example, a string of instructions being INTERPRETed 
cannot contain a LEAVE or ITERATE instruction (valid only within a 
repetitive DO loop) unless it also contains the whole repetitive DO ... END 
construct. 

A semicolon is implied at the end of the expression during execution, as a 
service to the user. 


Example: 

data='FRED 1 
interpret data '= 4* 

/* Will a) build the string "FRED = 4” */ 

/* b) execute FRED =4; */ 

/* Thus the variable "FRED" will be set to "4" */ 


Example: 


data='do 3; say 
interpret data 


"Hello there 1"; end' 

/* Would display: 
/* Hello therel 
/* Hello there! 
/* Hello there! 


V 

V 

V 

V 


Notes: 

1. Labels within the interpreted string are not permanent and are 
therefore ignored. Hence, executing a SIGNAL instruction from within 
an interpreted string will cause immediate exit from that string before 
the label search begins. 

2. If you are new to the concept of the INTERPRET instruction and are 
getting results that you do not understand, you may find that executing 
it with TRACE R or TRACE I set is helpful. 
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INTERPRET 


Example: 

/* Here we have a small program. */ 

Trace Int 
name='Kitty 1 
indirect= * name 1 

interpret 'say "Hello"' indirect'"!" 1 

when run gives the trace: 

2 *-* name='Kitty' 

>L> "Kitty" 

3 *-* indirect='name' 

>L> "name" 

4 *-* interpret 'say "Hello"' indirect'"!"' 


>L> 

"say 

"Hello"" 

>V> 

"name 

n 

>0> 

"say 

"Hello" name" 

>L> 

M it | it H 


>0> 

"say 

"Hello" name"!"" 


*-* say "Hello" name"!" 

>L> "Hello" 

>V> "Kitty" 

>0> "Hello Kitty" 

>L> "! " 

>0> "Hello Kitty!" 

Hello Kitty! 

Here, lines 2 and 3 set the variables used in line 4. Execution of line 4 
then proceeds in two stages. First the string to be interpreted is built 
up, using a literal string, a variable (INDIRECT), and another literal. 
The resulting pure character string is then interpreted, just as though it 
were actually part of the original program. Since it is a new clause, it 
is traced as such (the second *-* trace flag under line 4) and is then 
executed. Again a literal string is concatenated to the value of a 
variable (NAME) and another literal, and the final result (Hello 
Kitty!) is then displayed. 

3. For many purposes, the VALUE function (see page 99) may be used 
instead of the INTERPRET instruction. Line 4 in the last example 
could therefore have been replaced by: 

say "Hello" value(indirect)"!" 

INTERPRET is usually only required in special cases, such as when 
more than one statement is to be interpreted at once. 
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ITERATE 


ITERATE 


ITERATE [name]; 


ITERATE alters the flow within a repetitive DO loop (that is, any DO 
construct other than that with a simple DO). 

Execution of the group of instructions stops, and control is passed to the 
DO instruction just as though the bottom of the group of instructions had 
been reached. The UNTIL expression (if any) is tested, the control variable 
(if any) is incremented and tested, and the WHILE expression (if any) is 
tested. If these tests indicate that conditions of the loop have not yet been 
satisfied, the group of instructions is executed again (iterated), beginning at 
the top. 

If name is not specified, ITERATE will step the innermost active repetitive 
loop. If name is specified, it must be the name of the control variable of a 
currently active loop (which may be the innermost), and this is the loop 
that is stepped. Any active loops inside the one selected for iteration are 
terminated (as though by a LEAVE instruction). 

Example: 

do i=l to 4 

if i=2 then iterate 

say i 

end 

/* Would display the numbers: 1, 3, 4 */ 

Notes: 

1. name , if specified, must match that on the DO instruction. No 
substitution for compound variables is carried out when the comparison 
is made. 

2. A loop is active if it is currently being executed. If a subroutine is 
called (or an INTERPRET instruction is executed) during execution of 
a loop, the loop becomes inactive until the subroutine has returned or 
the INTERPRET instruction has completed. ITERATE cannot be used 
to step an inactive loop. 

3. If more than one active loop uses the same control variable, the 
innermost loop will be the one selected by the ITERATE. 
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LEAVE 


LEAVE 


LEAVE [name ]; 


LEAVE causes immediate exit from one or more repetitive DO loops (that 
is, any DO construct other than that with a simple DO). 

Execution of the group of instructions is terminated, and control is passed 
to the instruction following the END clause, just as though the END 
clause had been encountered and the termination condition had been met 
normally. However, on exit, the control variable (if any) will contain the 
value it had when the LEAVE instruction was executed. 

If name is not specified, LEAVE will terminate the innermost active 
repetitive loop. If name is specified, it must be the name of the control 
variable of a currently active loop (which may be the innermost), and that 
loop (and any active loops inside it) is then terminated. Control then passes 
to the clause following the END that matches the DO clause of the selected 
loop. 

Example: 

do i=l to 5 
say i 

if i=3 then leave 
end 

/* Would display the numbers: 1, 2, 3 */ 

Notes: 

1. name , if specified, must match that on the DO instruction. No 
substitution for compound variables is carried out when the comparison 
is made. 

2. A loop is active if it is currently being executed. If a subroutine is 
called (or an INTERPRET instruction is executed) during execution of 
a loop, the loop becomes inactive until the subroutine has returned or 
the INTERPRET instruction has completed. LEAVE cannot be used 
to terminate an inactive loop. 

3. If more than one active loop uses the same control variable, the 
innermost will be the one selected by the LEAVE. 
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NOP 


NOP 


NOP ; 


NOP is a dummy instruction that has no effect. It can be useful as the 
target of an THEN or ELSE clause: 

Example: 

Select 

when a=b then nop 
when a>b then say 
otherwise say 

end 

Note: Putting an extra semicolon instead of the NOP would merely insert 
a null clause, which would be ignored. The second WHEN clause would be 
seen as the first instruction expected after the THEN, and hence would be 
treated as a syntax error. NOP is an instruction that is a valid target for 
the THEN clause. 


/* Do nothing */ 

'A > B * 

'A < B 1 
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NUMERIC 


NUMERIC 


NUMERIC 


f DIGITS [ expression ] 

FORM 
FUZZ 


SCIENTIFIC 

ENGINEERING 


[expression ] 


The NUMERIC instruction is used to change the way in which arithmetic 
operations are carried out. The options of this instruction are described in 
detail on pages 133-142, but in summary: 

NUMERIC DIGITS 

controls the precision to which arithmetic operations will be carried 
out. expression (if specified) must evaluate to a positive whole 
number, and the default is 9. This number must be larger than the 
FUZZ setting. 

There is no limit to the value for DIGITS (except the amount of 
storage available), but note that high precisions are likely to be very 
expensive in CPU time. It is recommended that the default value be 
used wherever possible. 

NUMERIC FORM 

controls which form of exponential notation will be used for computed 
results. This may be either SCIENTIFIC (in which case only one, 
non-zero digit will appear before the decimal point), or 
ENGINEERING (in which case the power of ten will always be a 
multiple of three). The default is SCIENTIFIC. 

NUMERIC FUZZ 

controls how many digits, at full precision, will be ignored during a 
comparison operation, expression (if specified) must result in a 
non-negative whole number that must be less than the DIGITS 
setting. The default value for FUZZ is 0. 

The effect of FUZZ is to temporarily reduce the value of DIGITS by 
the FUZZ value before every comparison operation, so that the 
numbers are subtracted under a precision of DIGITS-FUZZ digits 
during the comparison and are then compared with 0. 

Note: The three numeric settings are automatically saved across 
subroutine and internal function calls. See under the CALL instruction 
(page 28) for more details. 
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OPTIONS 


OPTIONS 


OPTIONS [ expression ] ; 


The OPTIONS instruction specifies whether double byte character set 
(DBCS) strings can be manipulated. 

expression is evaluated, and the result is examined one word at a time. If 
one of the words is ETMODE, literal strings containing DBCS characters 
can be used in the program. If one of the words is NOETMODE, DBCS 
strings can not be used in the program. NOETMODE is the default. 

The last occurrence of NOETMODE or ETMODE appearing in the result is 
the setting that remains in effect. Any other words that appear in the 
result are ignored. For example, if you issue: 

OPTIONS USED TO SET NOETMODE OR ETMODE SETTING 
then ETMODE is the setting in effect. 

For a description of double byte character set (DBCS) strings, see VM/SP 
System Product Editor Command and Macro Reference. 

Notes: 

1. Because of the System Product Interpreter's scanning procedures, you 
are advised to place the OPTIONS instruction near the beginning of the 
EXEC file. 

2. The OPTIONS setting will be saved and restored across subroutine and 
function calls. 

3. To distinguish DBCS characters from one-byte EBCDIC characters, 
sequences of DBCS characters are enclosed with a shift-out (SO) 
character and a shift-in (SI) character. The hexadecimal value of the 
SO character is X'OE'. The hexadecimal value of the SI character is 
X'OF'. 

DBCS fields within a literal string, which are delimited by SO-SI 
characters, are excluded from the search for a closing quote in literal 
strings. 

4. The keywords ETMODE and NOETMODE can appear several times 
within the result. The last valid keyword specified takes effect. 
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PARSE 


PARSE 


PARSE UPPER 

fARG 1 

[template] ; 


EXTERNAL 


NUMERIC 


< 

PULL 

> 


SOURCE 

, ■' .'.'. ' ' ' . 

VALUE [ expression ] WITH 

:■ ' . ' .. 


VAR name 



l VERSION j 

, ' . : : ,■ ; 

•• . .. • . - . • , 




Where: 

template 

is a list of symbols separated by blanks and/or “patterns.” 

The PARSE instruction is used to assign data (from various sources) to one 
or more variables according to the rules described in the section on parsing 
(page 123). 

If the UPPER option is specified, the data to be parsed is first translated to 
uppercase. Otherwise, no uppercase translation takes place during the 
parsing. 

If template is not specified, no variables will be set but action will be taken 
to get the data ready for parsing if necessary. Thus for PARSE 
EXTERNAL and PARSE PULL, a data string will be removed from the 
appropriate queue; and for PARSE VALUE, expression will be evaluated. 

The data used for each variant of the PARSE instruction is: 

PARSE ARG 

The string(s) passed to the program, subroutine, or function as the 
input parameter list are parsed. (See the ARG instruction for details 
and examples.) 

Note: The argument string(s) to a REXX program or internal routine 
may also be retrieved or checked by using the ARG built-in function, 
described on page 75. 

PARSE EXTERNAL 

The next string from the terminal input buffer (system external event 
queue) is parsed. This queue may contain data that is the result of 
external asynchronous events - such as user console input, or 
messages. If that queue is empty, a console read results. Note that 
this mechanism should not be used for “normal” console input, for 
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PARSE 


which PULL is more general, but rather it could be used for special 
applications (such as debugging) when the program stack cannot be 
disturbed. 

The number of lines currently in the queue may be found with the 
EXTERNALS built-in function, described on page 85. 

PARSE NUMERIC 

The current numeric controls (as set by the NUMERIC instruction, 
see page 44) are made available. These controls are in the order 
DIGITS FUZZ FORM. 

Example: 

9 0 SCIENTIFIC 

See “Numeric Information” on page 141. 

PARSE PULL 

The next string from the program stack (system-provided data queue) 
is parsed (see note). This queue can save a series of data strings. 

Data can be added to the beginning or end of the queue using the 
PUSH and QUEUE instructions respectively. The queue can also be 
altered by other programs in the system, and can be used as a means 
of communication between programs. 

The number of lines currently in the queue may be found with the 
QUEUED built-in function, described on page 91. 

Note: PULL and PARSE PULL read from the program stack. If that 
is empty, they read from the terminal input buffer; and if that too is 
empty, a console read results. (See the PULL instruction, on page 51, 
for further details.) 

PARSE SOURCE 

The data parsed describes the source of the program being executed. 

The source string contains the characters CMS, followed by either 
COMMAND, FUNCTION, or SUBROUTINE depending on whether 
the program was invoked as some kind of host command (for example, 
EXEC or macro), or from a function call in an expression, or via the 
CALL instruction. These two tokens are followed by the program 
filename, filetype, and filemode; each separated from the previous 
token by one or more blanks. (The filetype and filemode may be 
unknown if the program is being executed from storage, in which case 
the SOURCE string will have one * for each unknown value.) 
Following the filemode is the name by which the program was invoked 
(due to synonyms, this may not be the same as the filename). It may 
be in mixed case and will be truncated to 8 characters if necessary. (If 
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PARSE 


it cannot be determined, “?” is used as a placeholder). The final word 
is the initial (default) address for commands. 

If the interpreter was called from a program that set up a subcommand 
environment, the filetype is usually the name of the default address 
for commands - see page 20 for details. Note that if a PSW is used for 
the default address, the PARSE SOURCE string will use ? as the 
name of the environment. 

The string parsed might therefore look like this: 

CMS COMMAND REXTRY EXEC * rext CMS 

PARSE VALUE 

expression is evaluated, and the result is the data that is parsed. Note 
that WITH is a keyword in this context and so cannot be used as a 
symbol within expression . 

Thus, for example: 

PARSE VALUE time() WITH hours mins secs 

will get the current time and split it up into its constituent parts. 
PARSE VAR name 

The value of the variable specified by name is parsed, name must be a 
symbol that is valid as a variable name (that is, it may not start with a 
period or a digit). Note that the variable name may be included in the 
template, so that for example: 

PARSE VAR string wordl string 

will remove the first word from string and put it in the variable wordl , 
and 

PARSE UPPER VAR string wordl string 

will also translate the data from string to uppercase before it is 
parsed. 

PARSE VERSION 

Information describing the language level and the date of the 
interpreter is parsed. This consists of five words: first the string 
“REXX370”, then the language level description (for example, “3.40”), 
and finally the interpreter release date (for example, “17 Jan 1984”). 

Note: PARSE VERSION information should be parsed on a word 
basis rather than on an absolute column position. 




aT^ 
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PROCEDURE 


PROCEDURE 


PROCEDURE [EXPOSE name [name ] \name ].. . ] ; 


Where: 

name 

is a symbol, separated from any other names by one or more blanks. 

The PROCEDURE instruction may be used within an internal routine 
(subroutine or function) to protect all the existing variables by making 
them unknown to the following instructions. On executing a RETURN 
instruction, the original variables' environment is restored and any 
variables used in the routine are dropped. 

The EXPOSE option modifies this, in that the variables specified by name s 
are exposed, so that any references to them (including setting them and 
dropping them) refer to the variables' environment owned by the caller. If 
the EXPOSE option is used, at least one name must be specified. Any 
variables not specified by name on a PROCEDURE EXPOSE instruction 
are still protected. Hence, some limited set of the caller's variables can be 
made accessible, and these variables may be changed (or new variables in 
this set may be created). All these changes will be visible to the caller 
upon RETURN from the routine. 

The variables are exposed in sequence from left to right. It is not an error 
to specify a name more than once, or to specify a name that has not been 
used as a variable by the caller. 

Example: 

/* This is main program */ 
j = l; x.1= * a* 
call toft 

say j k m /* would display "1 7 M" */ 

exit 

toft: procedure expose j k x.j 

say j k x.j /* would display "1 K a" */ 
k=7; m=3 /* note "M" is not exposed */ 

return 

Note that if X.J in the EXPOSE list had been placed before J, the caller's 
value of J would not have been visible at that time, so X.l would not have 
been exposed. 

If a stem is declared in names , all possible compound variables whose 
names begin with that stem are exposed. (A stem is a symbol containing 
just one period, which is the last character. See page 14.) 
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Example: 

Procedure Expose i j a. b. 

/* This exposes "I", "J", and all variables whose */ 


/* name starts with "A." or "B." */ 

A.l= , 7* /* This will set "A.l" in the caller*s */ 

/* environment, even if it did not */ 

/* previously exist. */ 


Variables may be exposed through several generations of routines, if 
desired, by ensuring that they are included on all intermediate 
PROCEDURE instructions. 

Only one PROCEDURE instruction in each level of routine call is allowed, 
all others (and those met outside of internal routines) are in error. 

Notes: 

1. An internal routine need not include a PROCEDURE instruction, in 
which case the variables it is manipulating are those “owned” by the 
caller. 

2, It is suggested that the PROCEDURE instruction should be the first 
instruction executed after the CALL or function invocation - that is, it 
should be the first instruction following the label. This is not enforced. 

See the CALL instruction and function descriptions on pages 28 and 69 for 
details and examples of how routines are invoked. 
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PULL 


PULL [template ]; 


Where: 

template 

is a list of symbols separated by blanks and/or “patterns.” 

PULL is used to read a string from the program stack (system-provided 
data queue), see note. It is just a short form of the instruction: 

PARSE UPPER PULL [template] ? 

The current head-of-queue will be read as one string. If no template is 
specified, no further action is taken (and the data is thus effectively 
discarded). Otherwise, the data is translated to uppercase and then parsed 
into variables according to the rules described in the section on parsing 
(page 123). Use the PARSE PULL instruction if uppercase translation is 
not desired. 

Note: If the program stack is empty, the terminal input buffer is used. If 
that too is empty, a console read will occur. Conversely, if you 
“type-ahead” before an EXEC asks for your input, your input data is added 
to the end of the terminal input buffer and will be read at the appropriate 
time. The length of data in the program stack is restricted to 255 
characters. The length of data in the terminal input buffer is restricted to 
130 characters. 

Example: 

Say * Do you want to erase the file? Answer Yes or No: 1 
Pull answer . 

if answer='YES' then Erase filename filetype filemode 

Here the dummy placeholder “.” is used on the template so as to isolate the 
first word entered by the user. 

The number of lines currently in the queue may be found with the 
QUEUED built-in function, described on page 91. 


Part 2: Instructions 51 





PUSH 


PUSH 


PUSH [ expression ]; 


The string resulting from expression will be stacked LIFO - Last In, First 
Out - onto the most recently created buffer of the program stack 
(system-provided data queue), see note. If expression is not specified, a null 
string is stacked. 

Note: The length of the data in the program stack is restricted to 255 
characters. The program stack contains one buffer initially, but additional 
buffers may have been created using the CMS command MAKEBUF. 

Example: 

a=*Fred* 

push /* Puts a null line onto the stack */ 

push a 2 /* Puts "Fred 2" onto the stack */ 

The number of lines currently in the queue may be found with the 
QUEUED built-in function, described on page 91. 
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QUEUE 


QUEUE [expression ]; 


The string resulting from expression will be appended to the most recently 
created buffer of the program stack (system-provided data queue), see note. 
That is, it will be stacked FIFO - First In, First Out. If expression is not 
specified, a null string is queued. 

Note: The length of data in the program stack is restricted to 255 
characters. The program stack contains one buffer initially, but additional 
buffers may have been created using the CMS command MAKEBUF. 

Example: 

a='Toft * 

queue a 2 /* Enqueues "Toft 2" */ 

queue /* Enqueues a null line behind the last */ 

The number of lines currently in the queue may be found with the 
QUEUED built-in function, described on page 91. 
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RETURN 


RETURN [ expression ]; 


RETURN is used to return control (and possibly a result) from a REXX 
program or internal routine to the point, of its invocation. 

If no internal routine (subroutine or function) is active, RETURN is 
essentially identical to EXIT. (See page 37.) 

If a subroutine is being executed (see the CALL instruction), expression (if 
any) is evaluated, control passes back to the caller, and the REXX special 
variable RESULT is set to the value of expression. If expression is not 
specified, the special variable RESULT is dropped (becomes uninitialized). 
The various settings saved at the time of the CALL (tracing, addresses, etc.) 
are also restored. (See page 28.) 

If a function is being executed, the action taken is identical, except that 
expression must be specified on the RETURN instruction. The result of 
expression is then used in the original expression at the point where the 
function was invoked. See the description of functions on page 69 for more 
details. 

If a PROCEDURE instruction was executed within the routine (subroutine 
or internal function), all variables of the current generation are dropped 
(and those of the previous generation are exposed) after expression is 
evaluated and before the result is used or assigned to RESULT. 


/f 

f 
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The result of evaluating expression is displayed to the user. The result of 
expression may be of any length. 

Note: The data will be formatted (split up into shorter lengths, if 
necessary) to fit the terminal line size (which may be determined using the 
LINESIZE function). The line size is restricted to a maximum of 130 
characters. The line splitting is done by the interpreter, hence allowing 
any length data to be displayed. Lines are typed on a typewriter terminal, 
or displayed on a display terminal. If you are disconnected (in which case 
there is no “real” console, but data can still be written to the console log), 
or CP TERMINAL LINESIZE OFF has been issued (in which case 
LINESIZE = 0), SAY will use a default line size of 80. 

Example: 

data=100 

Say data ‘divided by 4 => 1 data/4 

/* Would display: "100 divided by 4 => 25" */ 


Part 2: Instructions 55 





SELECT 


SELECT 


SELECT 


WHEN 

expression 

[;] 

THEN 

[;] 

instruction 

WHEN 

expression 

hi 

THEN 

[;] 

instruction 



” OTHERWISE [;] 

“ instruction ~ 



. 

* 



SELECT is used to conditionally execute one of several alternative 
instructions. 

Each expression following a WHEN is evaluated in turn and must result in 
0 or 1. If the result is 1, the instruction following the THEN (which may be 
a complex instruction such as IF, DO, or SELECT) is executed and control 
will then pass to the END. If the result is 0, control will pass to the next 
WHEN clause. 

If none of the WHEN expressions evaluate to 1, control will pass to the 
instruction(s), if any, following OTHERWISE. In this situation, the 
absence of an OTHERWISE will cause an error. 


Example: 


State Fn Ft Fm 
Select 

when rc=Q then do 

erase Fn Ft Fm 
say 'File existed, 
end 

when rc=28 | rc=36 then say 'File 
otherwise 

say 'Unexpected return code' rc 
exit rc 

End /* Select */ 


Now erased' 
does not exist' 
'from STATE' 
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Notes: 

1. A null clause is not an instruction, so putting an extra semicolon after 
a WHEN clause is not equivalent to putting a dummy instruction. The 
NOP instruction is provided for this purpose. 

2. A variable called THEN cannot be used within expression , because the 
keyword THEN is treated differently, in that it need not start a clause. 
This allows the expression on the WHEN clause to be terminated by 
the THEN, without a ; (delimiter) being required. 
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SIGNAL 


SIGNAL 


labelname 

[VALUE] expression 


r~ —1 


ERROR 

ON 


HALT 

PEE- 


NOVALUE 



[syntax J 


Where: 

labelname 

is a symbol that is taken as a constant. 

The SIGNAL instruction causes an abnormal change in the flow of 
control, or (if ON or OFF is specified) controls the trapping of exceptions. 

In the case of neither ON nor OFF being specified: 

labelname is used directly, or is the result of expression if VALUE is 
specified All active pending DO, IF, SELECT, and INTERPRET 
instructions in the current routine are then terminated (that is, they 
cannot be reactivated). Control then passes to the first label in the 
program that matches the required string, as though the search had 
started from the top of the program. The match is done independently 
of alphabetic case, but otherwise the label must match exactly. 

Example: 

Signal fred; /* Jump to label "FRED" below */ 

Fred: say 'Hi! 1 

Since the search effectively starts at the top of the program, control will 
always pass to the first label in the program if duplicates are present. 
That is, duplicate labels are ignored. 
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In the case of ON or OFF being specified: 

The condition is either enabled (ON) to trap an event or disabled 
(OFF). When a condition is enabled and the corresponding event 
occurs, the corresponding action (described below) will be taken. The 
conditions and their corresponding events, which may be trapped, are: 

ERROR 

any host command returns a non-zero return code. 

HALT 

an external attempt is made to interrupt execution of the program, 
for example, by using the CMS immediate command, HI (Halt 
Interpretation). Refer to ‘‘Interrupting Execution and Controlling 
Tracing” on page 119. 

NOVALUE 

an uninitialized variable is used in an evaluated expression, or 
following the VAR keyword of the PARSE instruction, or in an 
UPPER instruction. NOVALUE will trap a return of LIT on a 
function call SYMBOL(‘name > ). 

SYNTAX 

an interpretation error is detected. 

The initial setting of all conditions is OFF. When a condition is disabled 
(either initially or if OFF has been specified) the trap is not in effect. So, 
when the corresponding event occurs, no special action is taken. 

When a condition is currently enabled (ON has been specified) the trap is 
in effect. So, when the corresponding event occurs, instead of the usual 
action at that point, the special action is taken - execution of the current 
instruction is terminated and a SIGNAL instruction is executed 
automatically. This causes control to pass to the first label in the program 
that matches the condition. 

Example: 

Signal on error 
erase 


ERROR: /* Program will continue from here */ 

say “Return code was" rc 

Once an event is trapped, its corresponding condition is disabled (before the 
SIGNAL takes place), and a new SIGNAL ON instruction is required to 
re-enable it. Therefore, for example, if the required label is not found, a 
normal Syntax Error exit will be taken, which traces the name of that label 
and the clause in which the event occurred. 


/* this command gives a non-zero */ 
/* return code */ 
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For ERROR and SYNTAX, the REXX special variable RC is set to the 
error return code or syntax error number respectively before control is 
transferred to the condition label. 

The conditions are saved on entry to a subroutine and are then restored on 
RETURN. This means that SIGNAL ON and SIGNAL OFF may be used 
in a subroutine without affecting the conditions set up by the caller. See 
under the CALL instruction (page 28) for more details. 

Notes: 

1. In all cases, whenever the event occurs corresponding to an enabled 
condition, the SIGNAL takes place immediately (and the current 
instruction is terminated). Therefore, the instruction during which an 
event occurs may be only partly executed (for example, if the event 
corresponding to SYNTAX occurs during the evaluation of the 
expression in an assignment, the assignment will not take place). Note 
that HALT and ERROR can only occur at clause boundaries, but could 
arise in the middle of an INTERPRET instruction. 

2. During interactive debug, all conditions are set OFF so that unexpected 
transfer of control does not occur should (for example) the user 
accidentally use an uninitialized variable while SIGNAL ON 
NOVALUE is active. For the same reason, a syntax error during 
interactive debug will not cause exit from the program, but is trapped 
specially and then ignored after a message is given. 

3. Certain execution errors are detected by the host interface either before 
execution of the program starts or after the program has exited. These 
errors cannot be trapped by SIGNAL ON SYNTAX, and are listed on 
page 177. 

Note that labels are clauses consisting of a single symbol followed by a 
colon. Any number of successive clauses may be labels; therefore, multiple 
labels are allowed before another type of clause. 


The Special Variable SIGl 

When any transfer of control due to a SIGNAL (or CALL) takes place, the 
line number of the clause currently executing is stored in the REXX special 
variable SIGL. This is especially useful for SIGNAL ON SYNTAX (see 
above) when the number of the line in error can be used, for example, to 
control an editor. Typically, code following the SYNTAX label may 
PARSE SOURCE to find the source of the data, then invoke an editor to 
edit the source file positioned at the line in error. Note that in this case 
the EXEC has to be reinvoked before any changes made in the editor can 
take effect. 



4 ~ ^ 

r: 
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Alternatively, SIGL may be used to help determine the cause of an error 
(such as the occasional failure of a function call), using the following 
section of code (or something similar): 

/* Standard handler for SIGNAL ON SYNTAX */ 
syntax: 

$error='REXX error* rc 'in line* sigl':* errortext(rc) 
say $error 

say sourceline(sigl) 
trace *?r'; nop 

This code displays the error message and line number, then displays the 
line in error, and finally drops into debug mode to allow you to inspect the 
values of the variables used at the line in error (for instance). This may be 
followed, in CMS, by the following lines, so that by pressing ENTER you 
will be placed in XEDIT as suggested above: 

call trace 'O' 

address command 'Dropbuf O' 

parse source . . $fn $ft $fm . 

push 'Command :'sigl; push 'Command EMSG' $error 
address cms 'Xedit' $fn $ft $fm 
exit rc 


Using SIGNAL with the INTERPRET Instruction 

If, as the result of an INTERPRET instruction, a SIGNAL instruction is 
issued or a trapped event occurs, the remainder of the string(s) being 
interpreted will not be searched for the given label. In effect, labels within 
interpreted strings are ignored. 
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TRACE 


TRACE 


? 

J :: •] 



! 




- 


L [ number ] 


ALL 

COMMANDS 

ERRORS 

INTERMEDIATES 

LABELS 

NORMAL | NEGATIVE 
OFF 

RESULTS 

SCAN 


Or, alternatively: 


TRACE 


string 

[value] expression 
symbol 


Where: 

number is a whole number, 
string or expression evaluates to: 

• a number option, 

• one of the valid prefix and/or alphabetic character (word) options shown 
above, or 

• null. 

symbol is taken as a constant, and is, therefore: 

• a number option, 

• one of the valid prefix and/or alphabetic character (word) options shown 
above. 

TRACE is primarily used for debugging. It controls the tracing action 
taken (that is, how much will be displayed to the user) during execution of 
a REXX program. The syntax of TRACE is more concise than other REXX 
instructions. The economy of key strokes for this instruction is especially 
convenient since TRACE is usually entered manually during interactive 
debugging. 
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The tracing action is determined from the option specified following 
TRACE, or from the result of evaluating expression. If the expression 
form is used, the keyword VALUE preceding it may be omitted as long as 
expression starts with a special character or operator (so it cannot be 
mistaken for a symbol or string). 

Alphabetic Character (Word) Options 

Although it is acceptable to enter the word in full, only the capitalized 
character is significant, all others are ignored. That is why these are 
referred to as alphabetic character options. 

TRACE actions taken correspond to the alphabetic character options as 
follows: 

All all clauses are traced (that is, displayed) before execution. 

Commands all host commands are traced before execution and any 
non-zero return code is displayed. 

Error any host command resulting in a non-zero return code is 

traced after execution. 

Intermediates all clauses are traced before execution. Intermediate 
results during evaluation of expressions and substituted 
names are also traced. 

labels are traced, not all labels, only those passed during 
execution. This is especially useful with debug mode, when 
the interpreter will pause after each label. It is also 
convenient for the user to make note of all subroutine calls 
and signals. 

(Negative or Normal); any host command resulting in a 
negative return code is traced after execution. This is the 
default setting. 

nothing is traced, and the special prefix actions (see below) 
are reset to OFF. 

all clauses are traced before execution. Final results 
(contrast with Intermediate, above) of evaluating an 
expression are traced. Values assigned during PULL, ARG, 
and PARSE instructions are also displayed. This setting 
is recommended for general debugging. 

all remaining clauses in the data will be traced without 
being executed. Basic checking (for missing ENDs etc.) is 
carried out, and the trace is formatted as usual. This is 
only valid if the TRACE S clause itself is not nested in any 
other instruction (including INTERPRET or interactive 
debug) or in an internal routine. 


Labels 

Negative 

Off 

Results 

Scan 
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Prefix Options 

The prefixes ! and ? are valid either alone or with one of the alphabetic 
character options. Both prefixes may be specified, in any order, on one 
TRACE instruction. A prefix may be specified more than once, if desired. 
Each occurrence of a prefix on an instruction reverses the action of the 
previous prefix. The prefix(es) must immediately precede the option (no 
intervening blanks). 

The prefixes ! and ? modify tracing and execution as follows: 

? is used to control interactive debug. During normal execution, a 
TRACE instruction prefixed with ? will cause interactive debug to be 
switched on. (See separate section on page 117 for full details of this 
facility). While interactive debug is on, interpretation will pause after 
most clauses that are traced. As an example, the instruction TRACE ?E 
will make the interpreter pause for input after executing any host 
command that returns an Error (that is, a non-zero return code). 

Any TRACE instructions in the file being traced are ignored. (This is so 
that you are not taken out of interactive debug unexpectedly.) 

Interactive debug can be switched off, when it is in effect, by issuing a 
TRACE instruction with a prefix ?. Repeated use of the ? prefix will, 
therefore, switch you alternately in and out of interactive debug. Or, 
interactive debug can be turned off at any time by issuing TRACE O or 
TRACE with no options. 

Note: The CMS immediate command TS, entered from the command 
line, can also be used to enter interactive debug. 

! is used to inhibit host command execution. During normal execution, a 
TRACE instruction prefixed with ! will cause execution of all 
subsequent host commands to be suspended. As an example, TRACE IC 
will cause commands to be traced but not executed. As each command is 
bypassed, the REXX special variable RC is set to 0. This action may be 
used for debugging potentially destructive programs. (Note that this 
does not inhibit any commands issued manually while in interactive 
debug, which are always executed.) 

Command inhibition can be switched off, when it is in effect, by issuing 
a TRACE instruction with a prefix !. Repeated use of the ! prefix will, 
therefore, switch you alternately in and out of command inhibition 
mode. Or, command inhibition can be turned off at any time by issuing 
TRACE O or TRACE with no options. 
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Numeric Options 


If interactive debug is active, and if the option specified is a positive whole 
number (or an expression that evaluates to one), that number indicates the 
number of debug pauses to be skipped over. (See the section on interactive 
debugging, page 117, for further information.) However, if the option is a 
negative number (or an expression that evaluates to one), all tracing, 
including debug pauses, is temporarily inhibited for the specified number of 
clauses. For example, TRACE -100 means that the next 100 clauses that 
would normally be traced, will not, in fact, be displayed. After that, tracing 
will resume as before. 

If interactive debug is not active, numeric options are ignored. 

If no option is specified on a TRACE instruction, or if the result of 
evaluating the expression is null, the default tracing actions are restored. 
The defaults are TRACE N, command inhibition (!) off, and interactive 
debug (?) off. 

The trace actions currently in effect can be retrieved by using the TRACE 
built-in function, described on page 97. 

Comments associated with a traced clause are included in the trace, as are 
comments in a null clause, if TRACE A, R, I, or S is specified. 

Commands traced before execution always have the final value of the 
command (that is, the string passed to the environment), as well as the 
clause generating it traced. 

Trace actions are automatically saved across subroutine and function calls. 
See under the CALL instruction (page 28) for more details. 


A Typical Example 


One of the most common traces you will use is: 

TRACE ?R 

/* Interactive debug is switched on if it was off, */ 

/* and tracing Results of expressions begins. */ 

Note: Tracing may be switched on, without requiring modification to a 
program, by using the CMS command SET EXECTRAC ON. Tracing may 
also be turned on or off asynchronously, (that is, while an EXEC is 
running) using the TS and TE immediate commands. See page 119 for the 
description of these facilities. 
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Format of TRACE output 

Every clause traced will be displayed with automatic formatting 
(indentation) according to its logical depth of nesting etc., and any control 
codes (defined as EBCDIC values less than X'40') are replaced by a question 
mark (?) to avoid console interference. Results (if requested) are indented 
an extra two spaces and are enclosed in double quotes so that leading and 
trailing blanks are apparent. 

The first clause traced on any line will be preceded by its line number. If 
the line number is greater than 99999, it is truncated on the left and the 
truncation is indicated by a prefix of ?. For example the line number 100354 
would be shown as ?00354. 

All lines displayed during tracing have a three character prefix to identify 
the type of data being traced. These may be: 

*-* identifies the source of a single clause, that is, the data actually in 
the program. 

+++ identifies a trace message. This may be the non-zero return code 
from a command, the prompt message when interactive debug is 
entered, an indication of a syntax error when in interactive debug, 
or the traceback clauses after a syntax error in the program (see 
below). 

>>> identifies the Result of an expression (for TRACE R), or the value 
assigned to a variable during parsing, or the value returned from a 
subroutine call. 

> . > identifies the value “assigned” to a placeholder during parsing (see 
page 129). 

The following prefixes are only used if Intermediates (TRACE I) are being 
traced: 

>C> The data traced is the name of a compound variable, traced after 

substitution and before use, provided that the name had the value of 
a variable substituted into it. 

>F> The data traced is the result of a function call. 

>L> The data traced is a literal (string or uninitialized variable). 

>0> The data traced is the result of an operation on two terms. 

>P> The data traced is the result of a prefix operation. 

>V> The data traced is the contents of a variable. 

Following a syntax error that is not trapped by SIGNAL ON SYNTAX, the 
clause in error will always be traced, as will any CALL or INTERPRET or 
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function invocation clauses active at the time of the error. If the error was 
caused by an attempt to transfer control to a label that could not be found, 
that label is also traced. These traceback lines are identified by the special 
trace prefix +++. 
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UPPER 


UPPER variable [variable ] [variable] . . ; 


Where: 

variable 

symbol, separated from any other variables by one or more blanks. 

UPPER may be used to translate the contents of one or more variables to 
uppercase. The variables are translated in sequence from left to right. 

It is more convenient (and faster) than using repeated invocations of the 
TRANSLATE function. 

Example: 

a= * Hello 1 ; b='there 1 
Upper a b 

say a b /* would display "HELLO THERE" */ 

Only simple symbols and compound symbols may be specified (see page 13). 
An error is signalled if a constant symbol or a stem is encountered. Using 
an uninitialized variable is not an error, and has no effect, except that it 
will be trapped if the NO VALUE condition (SIGNAL ON NO VALUE) is 
enabled. 
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Syntax 


Calls to internal and external routines (called functions may be included 
in an expression anywhere that a data term (such as a string) would be 
valid, using the notation: 

function-name( [expression][,expression]... ) 

Where: 

function-name is a string, or a symbol that is taken as a constant. 

There may be up to ten expressions, separated by commas, between the 
parentheses. These are called the arguments to the function. Each 
argument expression may include further function calls. 

Note: Generally speaking, the last operand after the comma may be 
omitted. No error is flagged in this case. 

Note that the name of the function must be adjacent to the “(”> with no 
blank in between, or the construct will not be recognized as a function call. 

(A blank operator will be assumed at this point instead.) 

The arguments are evaluated in turn from left to right and they are all then 
passed to the function. This then executes some operation (usually 
dependent on the argument strings passed, though arguments are not 
mandatory) and will eventually return a single character string. This 
string is then included in the original expression just as though the entire 
function reference had been replaced by the name of a variable that 
contained that data. 

For example, the function SUBSTR is built-in to the interpreter (see below, 
page 94) and could be used as: 

Nl='abcdefghijk' 

Zl='Part of N1 is: 'Substr(c,2,7) 

/* would set Z1 to 'Part of N1 is: bcdefgh' */ 

A function may have no arguments, but parentheses must always be written 
(otherwise the function call would not be recognized). 

date() /* returns the date in the default format dd Mmm yyyy */ 
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Calls to Functions and Subroutines 

The function calling mechanism is identical to that for subroutines. The 
only difference between functions and subroutines is that functions must 
return data, whereas subroutines need not. The various types of routines 
that can be called as functions may be: 

Internal If the routine name exists as a label in the program, the current 
interpretation status is saved, so that it will later be possible to 
return to the point of invocation to resume execution. Control is 
then passed to the label found. As with a routine invoked by the 
CALL instruction, various other status information (TRACE and 
NUMERIC settings, etc.) is saved too. See the CALL instruction 
(page 28) for details of this. If an internal routine is to be called 
as a function, any RETURN instruction executed to return from 
it must have an expression specified. This is not necessary if it is 
only called as a subroutine. 



Example: 

/* Recursive internal function execution... */ 
arg x 
say x'l =' 
exit 

factorial: 
arg n 

if n=0 then return 1 V.,,/' 

return factorial(n-1) * n 


factorial(x) 

procedure /* calculate factorial by.. */ 
/* .. recursive invocation. */ 


(Unusually, FACTORIAL also calls itself. The PROCEDURE 
instruction ensures that a new variable n is created for each 
invocation). 

Built-in These functions are always available, and are defined in the next 
section of this manual. (See pages 73-103.) 

External Users may write or make use of functions that are external to 
the user's program and to the interpreter. An external function 
may be written in any language, including REXX, that supports 
the system dependent interfaces used by the interpreter to invoke 
it. Again, when called as a function it must return data to the 
caller. 

Notes: 

1. Calling an external program as a function is similar to 

calling an internal routine. The external routine is however 
an implicit PROCEDURE in that all the caller's variables are 
always hidden, and the status of internal values (NUMERIC 
settings, etc.) start with their defaults (rather than inheriting 
those of the caller). 
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2. Other REXX programs may be called as functions. Either 
EXIT or RETURN may be used to leave the other REXX 
program, and in either case an expression must be specified. 


Search Order 


The search order for functions is the same as in the list above. That is, 
internal labels take precedence, then built-in functions, and finally external 
functions. 

Internal labels are not used if the function name is given as a string (that 
is, is specified in quotes) - in this case the function must be built-in or 
external. This lets you usurp the name of, say, a built-in function to extend 
its capabilities, yet still be able to invoke the built-in function when needed. 

Example: 

/* Modified DATE to return sorted date by default */ 
date: procedure 
arg in 

if in=* 1 then in='Sorted' 
return 'DATE'(in) 

Built-in functions have uppercase names, and so the name in the literal 
string must be in uppercase for the search to succeed, as in the example. 

The same is usually true of external functions. 

External functions and subroutines have a special search order: 

1. The name is prefixed with RX, and the interpreter attempts to execute 
the program of that name, using SVC 202. 

2. If the function is not found, the function packages will be interrogated 
and loaded if necessary (they return RC = 0 if they contained the 
requested function, or RC = 1 otherwise). The function packages are 
checked in the order RXUSERFN, RXLOCFN, and RXSYSFN. If the 
load is successful, step (1) is repeated and will succeed. 

3. If still not found, the name is restored to its original form, and all disks 
are first checked for a program with the same filetype as the currently 
executing program (if the filetype is not EXEC, as with XEDIT macros 
for example), and then checked for a file with the filetype of EXEC. If 
either is found, control is passed to it. (The IMPEX setting has no 
control over this.) 

4. Finally the interpreter attempts to execute the function under its 
original name, using SVC 202. (If still not found, an error results.) 

The name prefix mechanism, RX, allows new REXX functions to be written 
with little chance of name conflict with existing MODULES. 
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Errors during Execution 

If an external or built-in function detects an error of any kind, the 
interpreter is informed, and a syntax error results. Execution of the clause 
that included the function call is therefore terminated. Similarly, if an 
external function fails to return data correctly, this will be detected by the 
interpreter and reported as an error. 

If a syntax error occurs during the execution of an internal function, it may 
be trapped (using SIGNAL ON SYNTAX) and recovery may then be 
possible. If the error is not trapped, execution of the whole program is 
terminated in the usual way. 


Built-in Functions 

REXX provides a rich set of built-in functions. These include character 

manipulation, conversion, and information functions. Further external 

functions are generally available - see page 103. 

General notes on the built-in functions: 

• The built-in functions work internally with NUMERIC DIGITS 9 and 
NUMERIC FUZZ 0 and are unaffected by changes to the NUMERIC 
settings, except where stated. 

• Where a string is referenced, a null string may be supplied. 

• If an argument specifies a length, it must be a non-negative whole 
number. If it specifies a start character or word in a string, it must be a 
positive whole number. 

• Where the last argument is optional, a comma may always be included 
to indicate that it has been omitted; for example, DATATYPE(1,), like 
DATATYPE(l), would return NUM. 

• pad character, if specified, must be exactly one byte long. 

• If a function has a sub-option selected by the first character of a 
keyword, that character may be in upper- or lowercase. 


ABBREV 


ABBRE Y(information,info[,length ]) 


returns 1 if info is equal to the leading characters of information and 
info is not less than the minimum length. Returns 0 if either of these 
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conditions is not met. The minimum length may be specified as the third 
argument; the default is the length of info. 


Here are some examples: 


ABBREV('Print' 

,'Pri') 

-> 

1 

ABBREV('PRINT' 

,'Pri') 

-> 

0 

ABBREV('PRINT' 

,'PRI',4) 

-> 

0 

ABBREV('PRINT' 

,'PRY') 

-> 

0 

ABBREV('PRINT' 


-> 

1 

ABBREV('PRINT' 

,’M) 

-> 

0 


Note: A null string will always match if a length of 0 (or the default) is 
used. This allows a default keyword to be selected automatically if desired; 
for example: 

say ’Enter option:'; pull option . 
select /* keywordl is to be the default */ 
when abbrev('keywordl',option) then ... 
when abbrev(*keyword2option) then ... 

otherwise nop; 
end; 


ABS 


ABS (number) 


returns the absolute value of number. The result is formatted according to 
the current setting of NUMERIC DIGITS. 


Here are some examples: 

ABS ('12.3') -> 12.3 

ABSC -0.307') -> 0.307 


ADDRESS 


ADDRESS () 


returns the environment to which host commands are currently being 
submitted. In CMS, the environment may be a name of a subcommand 
environment or a PSW. Trailing blanks are removed from the result. 

Here are some examples: 
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ADDRESS() 
ADDRESS() 


-> 'CMS' /* perhaps */ 

-> 'XEDIT 1 /* perhaps */ 


ARG 


ARG([n[ ,option] ] ) 


returns information about the argument strings to a program or internal 
routine. 

If no parameter is given, the number of arguments passed to the program or 
internal routine is returned. 

If only n is specified, the nth argument string is returned. If the argument 
string does not exist, the null string is returned, n must be positive. 

If option is specified, the function tests for the existence of the nth 
argument string. Valid options (of which only the capitalized letter is 
significant, all others are ignored) are: 

Exists returns 1 if the nth argument exists; that is, if it was explicitly 
specified when the routine was called. Returns 0 otherwise. 

Omitted returns 1 if the nth argument was omitted; that is, if it was not 
explicitly specified when the routine was called. Returns 0 
otherwise. 


Here are some examples: 


/* following "Call name;" (no arguments) */ 
ARGO -> 0 

ARG(1) -> 

ARG(2) -> 1 1 

ARG(1, 1 e 1 ) -> 0 

ARG (lO O') -> 1 


/* following "Call name 'a',Ob'; */ 


ARGO 

-> 

ARG(1) 

-> 

ARG(2) 

-> 

ARG(3) 

-> 

ARG(n) 

-> 

ARG(1,'e') 

-> 

ARG(2,'E') 

-> 

ARG(2,'0') 

-> 

ARG(3,'o’) 

-> 

ARG(4,'o') 

-> 


3 

a 

i i 

b 

1 ' /* for n>=4 */ 

1 
0 
1 
0 
1 


Notes: 


1. The argument strings to a program may be retrieved and parsed directly 
using the ARG or PARSE ARG instructions - see pages 26, 46, and 123. 
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2. Programs called as commands can have only 0 or 1 argument strings. 


BITAND 


BITAND(s*rmgi[,[ string2 ] [,pad]]) 


returns a string composed of the two input strings logically AND'ed 
together, bit by bit. The length of the result is the length of the longer of 
the two strings. If no pad character is provided, the AND operation 
terminates when the shorter of the two strings is exhausted and the 
unprocessed portion of the longer string is appended to the partial result. If 
pad is provided, it is used to extend the shorter of the two strings on the 
right, before carrying out the logical operation. The default for string2 is 
the zero length (null) string. 


Here are some examples: 


BITAND('73 1 x,'27'x) 

-> 

*23’x 

BITAND('13'x,'5555'x) 

-> 

* 1155 * x 

BITAND('13'x,'5555'x,'74'X) 

-> 

*1154•x 

BITAND('pQrS',,'BF'x) 

-> 

'pqrs * 


BITOR 


BITOH($tringl [,[ string2 ] [,pad] ]) 


returns a string composed of the two input strings logically ORed together, 
bit by bit. The length of the result is the length of the longer of the two 
strings. If no pad character is provided, the OR operation terminates when 
the shorter of the two strings is exhausted and the unprocessed portion of 
the longer string is appended to the partial result. If pad is provided, it is 
used to extend the shorter of the two strings on the right, before carrying 
out the logical operation. The default for string2 is the zero length (null) 
string. 


Here are some examples: 


BITOR('15'x,'24'x) 

-> 

' 35' x 

BITOR( 1 15'x,'2456'x) 

-> 

'3556'x 

BITOR('15'x,'2456'x,'FO'x) 

-> 

'35F6'x 

BITOR('llll'x,, 1 4D 1 x) 

-> 

'5D5D'x 

BITOR('Fred',,'40'x) 

-> 

'FRED' 
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BITXOR 


CENTRE/CENTER 


BITXOR (string 1 [,[ string2] [ ,pad]] ) 


returns a string composed of the two input strings logically exclusive ORed 
together, bit by bit. The length of the result is the length of the longer of 
the two strings. If no pad character is provided, the XOR operation 
terminates when the shorter of the two strings is exhausted and the 
unprocessed portion of the longer string is appended to the partial result. If 
pad is provided, it is used to extend the shorter of the two strings on the 
right, before carrying out the logical operation. The default for string2 is 
the zero length (null) string. 


Here are some examples: 



BITXOR( 1 12 ' x, ' 22 ' x) 

-> 

' 30 1 x 

BITXOR(' 1211 1 x, ' 22 ' x) 

-> 

1 3011*x 

BITXOR( 'C711'x, ' 222222'x, 1 ' ) 

-> 

1 E53362 1 x 

BITXOR( 'llll'x, ' 444444 ' x) 

-> 

* 555544 1 x 

BITXOR( 'llll'x, ' 444444 ' x,’40'x) 

-> 

1 555504 1 x 

BITXOR(' llll'x,,’4D'x) 

-> 

' 5C5C 1 x 


CENTER (string , length 

.. . pad, . 

) 

CENTRE ( string , length 

, pad 

\) 


returns a string of length length with string centered in it, with pad 
characters added as necessary to make up length. The default pad 
character is blank. If the string is longer than length, it will be truncated 
at both ends to fit. If an odd number of characters are truncated or added, 
the right hand end loses or gains one more character than the left hand 
end. 


Here are some examples: 


CENTER(abc,7) 


-> 

' ABC ' 

CENTER(abc,8,'-') 


-> 

' —ABC- 

CENTRE(’The blue 

sky',8) 

-> 

'e blue s 

CENTRE('The blue 

sky',7) 

-> 

'e blue ' 


Note: This function may be called either CENTRE or CENTER, which 
avoids errors due to the difference between the British and American 
spellings. 
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CMSFLAG 


This is part of the RXSYSFN package. See page 104. 


COMPARE 


COMPARE (string 1 , string2 [ y pad ] ) 


returns 0 if the strings, stringl and string2, are identical. If they are 
not, the returned number is non-zero and is the position of the first 
character that does not match. The shorter string is padded on the right 
with pad if necessary. The default pad character is a blank. 


Here are some examples: 


COMPARE('abc','abc') 

-> 

0 

COMPARE('abc','ak 1 ) 

-> 

2 

COMPARE(’ab ',•ab') 

-> 

0 

COMPARE('ab ’,'ab 1 ,' ’) 

-> 

0 

COMPARE('ab ','ab','x') 

-> 

3 

COMPARE('ab— ','ab','-') 

-> 

5 


COPIES 



J' ./ ' . 

COPIES (string,n) 



returns n concatenated copies of string, n must be positive or 0. 
Here are some examples: 

COPIES('abc 1 ,3) -> 'abcabcabc' 

COPIES('abc*,0) -> * * 


C2D 


C2D (string [,n]) 


Character to Decimal. Returns the decimal value of the binary 
representation of string. If the result cannot be expressed as a whole 
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number, an error results. That is, the result must not have more digits than 
the current setting of NUMERIC DIGITS. 


string may be the null string. 


If n is not specified, string is taken to be an unsigned number: 


Here are some examples: 


C2D('09’x) 

-> 

9 

C2D('81'x) 

-> 

129 

C2D{'a') 

-> 

129 

C2D ( 1 FF81'x) 

-> 

65409 


If n is specified, the binary value of the string is taken to be a two's 
complement number expressed in n characters, and is converted to a REXX 
whole number which may therefore be negative. If n is 0, 0 is always 
returned. 


The string is padded on the left with characters of '00'X (note, not 
“sign-extended”) or truncated to length n characters, if necessary. That is, 
as though RIGHT (string,n, ’00’x) had been executed. 


Here are some examples: 


C2D('81 1 x,1) 

-> 

-127 

C2D('81'x,2) 

-> 

T29 

C2D( 1 FF81'x,2) 

-> 

-127 

C2D('FF81 1 x,1) 

-> 

-127 

C2D('FF7F 1 x,1) 

-> 

127 

C2D('F081'x,2) 

-> 

-3967 

C2D('F081'x,1) 

-> 

-127 

C2D('0031'x,0) 

-> 

0 


Implementation maximum: The input string may not have more than 
250 characters that will be significant in forming the final result. Leading 
sign characters (‘00’x and ‘ff x) do not count towards this total. 


C2X 


C2 X(string) 


Character to Hexadecimal. Converts a character string to its hexadecimal 
representation (unpacks). The data to be unpacked may be of any length. 


Here are some examples: 

C2X( 1 72s *) -> * F7F2A2 1 

C2X(’012 3'x) -> '0123' 
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DATATYPE 



If only string is specified, the returned result is NUM if string is a valid 

REXX number (any format), or CHAR otherwise. 

If type is specified, the returned result is 1 if string matches the type, or 

0 otherwise. If string is null, 0 is returned (except when type is X, which 

returns 1.) The valid types (of which only the capitalized letter is 

significant, all others are ignored) are: 

Alphanumeric returns 1 if the input only contains characters from the 
ranges a-z, A-Z, and 0-9. 

Bits returns 1 if the input only contains the characters 0 and/or 

1 . 

Lowercase returns 1 if the input only contains characters from the 
range a-z. 

Mixed case returns 1 if the input only contains characters from the 
ranges a-z and A-Z. 

Number returns 1 if the input is a valid REXX number. 

Symbol returns 1 if the input only contains characters that are 

valid in REXX symbols (see page 5). Note that not only 
upper case alphabetics are permitted, but lower case 
alphabetics as well. 

Uppercase returns 1 if the input only contains characters from the 
range A-Z. 

Whole number returns 1 if the input is a REXX whole number under the 
current setting of NUMERIC DIGITS. 

hexadecimal returns 1 if the input only contains characters from the 
ranges a-f, A-F, 0-9, and blank (so long as blanks only 
appear between pairs of hexadecimal characters.) Also 
returns 1 if the input is a null string. 
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Here are some examples: 


DATATYPE( 

1 12 1 

) 


-> 

NUM 

DATATYPE( 

1 ’ ) 



-> 

CHAR 

DATATYPE( 

• 123* 1 

) 


-> 

CHAR 

DATATYPE( 

1 12.3 1 

r 

'N' ) 

-> 

1 

DATATYPE( 

'12.3' 

/ 

'W' ) 

-> 

0 

DATATYPE( 

* Fred * 

r 

' M' ) 

-> 

1 

DATATYPE( 

1 1 , *M* 

) 


-> 

0 

DATATYPE( 

1 Fred 1 

r 

'L' ) 

-> 

0 

DATATYPE( 

' $20K 1 

r 

'S' ) 

-> 

1 

DATATYPE( 

' BCd3 * 

t 

'X' ) 

-> 

1 

DATATYPE( 

'BC d3 

i 

, *X’ ) 

-> 

1 


DATE 


DATE ([option]) 


returns the local date in the format: dd Mmm yyyy; for example, 27 Aug 
1983, with no leading zero on the day. The following options (of which 
only the capitalized letter is signifigant, all others are ignored) may be 
supplied to obtain alternative formats: 

Basedate returns the number of days since the base date January 1, 0001. 

The expression DATE (B) //! returns a number in the range 
0-6, where 0 is Monday and 6 is Sunday. 

Thus, this function can be used to determine the day of the week 
independent of the national language you're working in. 

Note: The origin of January 1, 0001 is based on the Gregorian 
calendar. Though this calendar did not exist prior to 1582, 
Basedate is calculated as if it did: 365 days per year, an extra day 
every four years except century years, and leap centuries if the 
century is divisible by 400. It does not take into account any 
errors in the calendar system that created the Gregorian 
calendar originally. 

Century returns number of days since January 1 of the last year which is 
a multiple of 100 in the format: ddddd (no leading zeros). 

Example: if a call is made to DATE(C) on June 30, 1985, the 
number of days from January 1, 1900 to June 30, 1985 will be 
returned. 

Days returns number of days so far in this year (beginning with 1) in 
the format: ddd (no leading zeros). 

European returns date in the format: dd/mm/yy. 
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Julian returns date in “OS” format: yyddd. 

Month returns full name of the current month, for example, August 

Ordered returns date in the format: yy/mm/dd (suitable for sorting, etc.) 

Sorted returns date in the format: yyyymmdd (suitable for sorting, etc.) 

Usa returns date in the format: mm/dd/yy. 

Weekday returns day of the week, for example, Tuesday 

Note: The first call to DATE or TIME in one expression causes a time 
stamp to be made which is then used for all calls to these functions in that 
expression. Hence if multiple calls to any of the DATE and/or TIME 
functions are made in a single expression, they are guaranteed to be 
consistent with each other. 

DELSTR 



deletes the substring of string that begins at the nth character, and is of 
length length. If length is not specified, the rest of string is deleted. If 
n is greater than the length of string, the string is returned unchanged, 
n must be a positive whole number. 

Here are some examples: 

DELSTR(* abed ' , 3) -> » ab 1 

DELSTR(' abede' ,3,2) -> ’ abe* 

DELSTR( 1 abode 1 ,6) -> 'abede* 

DELWORD 



deletes the substring of string that starts at the nth word. The length 
option refers td the number of blank-delimited words. If length is omitted, 
it defaults to be the remaining words in string, n must be a positive 
whole number. If n is greater than the number of words in string, 
string is returned unchanged. The string deleted includes any blanks 
following the final word involved. 
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Here are some examples: 


DELWORD( 

'Now 

is 

the 

time' ,2,2) 

-> 

'Now 

time' 

DELWORD( 

'Now 

is 

the 

time ',3) 

-> 

'Now 

is ' 

DELWORD( 

'Now 

is 

the 

time',5) 

-> 

'Now 

is the 


DIAG/DIAGRC 

These are part of the RXSYSFN package. See page 105. 


D2C 


D2C (whole-number [,n]) 


Decimal to Character. Returns a character string which is the binary 
representation of the decimal number. Length may be specified by n, or 
length is as needed if n is omitted. 

whole-number must be a non-negative number unless n is specified, or an 
error will result. If n is not specified, the result is returned such that there 
are no leading Wx characters. 

If n is specified, it is the length of the final result in characters; that is, 
after conversion the input string will be sign-extended to the required 
length. If the number is too big to fit into n characters, it will be truncated 
on the left. 


Here are some examples: 


D2C(9) 

-> 

' 09' x 

D2C(129) 

-> 

' 81' x 

D2C{129,1) 

-> 

' 81' x 

D2C(129,2) 

-> 

' 0081'x 

D2C(257,1) 

-> 

' 01' x 

D2C(-127,1) 

-> 

’ 81' x 

D2C(-127,2) 

-> 

'FF81'x 

D2C(-1,4) 

-> 

'FFFFFFFF'X 

D2C(12,0) 

-> 

i • 


Implementation maximum: The output string may not have more than 
250 significant characters, though a longer result is possible if it has 
additional leading sign characters (‘00’x and ‘ff x). 
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D2X 


D2X( whole-number [,n]) 


Decimal to Hexadecimal. Returns a string of hexadecimal characters which 
is the hexadecimal (unpacked) representation of the decimal number. 

whole-number must be a non-negative number unless n is specified, or an 
error will result. If n is not specified, the result is returned such that there 
are no leading 0 characters. 

If n is specified, it is the length of the final result in characters; that is, 
after conversion the input string will be sign-extended to the required 
length. If the number is too big to fit into n characters, it will be truncated 
on the left. 


Here are some examples: 

D2X{9) -> 

'9* 

D2X(129) 

-> 

'81' 

D2X(129,1) 

-> 

'1' 

D2X(129,2) 

-> 

'81' 

D2X(129,4) 

-> 

'0081 

D2X(257,2) 

-> 

'01* 

D2X(-127,2) 

-> 

' 81 1 

D2X(-127,4) 

-> 

1 FF81 

D2X(12,0) 

-> 

t i 


Implementation maximum: The output string may not have more than 
500 significant hexadecimal characters, though a longer result is possible if 
it has additional leading sign characters (0 and F). 

ERRORTEXT 


ERRORTEXT (n) 


returns the error message associated with error number n. n must be in 
the range 0-99, and any other value is an error. If n is in the allowed range, 
but is not a defined REXX error number, the null string is returned. 

Here are some examples: 

ERRORTEXT(16) -> 'Label not found' 

ERRORTEXT(60) -> ' ' 
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EXTERNALS 


EXTERNALS () 


returns the number of elements in the terminal input buffer (system 
external event queue), that is, the number of logical typed-ahead lines, if 
any. See PARSE EXTERNAL on page 46 for a description of this queue. 

Here is an example: 

EXTERNALS() -> 0 /* Usually */ 


FIND 


FIND (string .phrase) 


searches string for the first occurrence of the sequence of blank-delimited 
words phrase, and returns the word number of the first word of phrase in 
string. Multiple blanks between words are treated as a single blank for 
the comparison. Returns 0 if phrase is not found. 

Here are some examples: 

FIND (*now is the time*, 'is the time*) -> 2 

FIND ('now is the time','is the') -> 2 

FIND ('now is the time*is time ') -> 0 


FORMAT 


FORMAT(Vmmfter [, [before ] [, [after ] [, [expp ] [,expt ]]]]■)'. 


rounds and formats number. 

If only number is given, it will be rounded and formatted to standard REXX 
rules, just as though the operation “number+ 0” had been carried out. 
before and after describe how many characters are to be used for the 
integer part and decimal part of the result respectively. If either of these is 
omitted the number of characters used will be as many as are needed for 
each part. 
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If before is not large enough to contain the integer part of the number, an 
error results. If before is too large, the number is padded on the left with 
blanks. If after is not the same size as the decimal part of the number, the 
number will be rounded (or extended with zeros) to fit. Specifying 0 will 
cause the number to be rounded to an integer. 


Here are some examples: 



FORMAT{'3',4) 

-> 

• 3' 

FORMAT('1.73',4,0) 

-> 

' 2* 

FORMAT('1.73',4,3) 

-> 

* 1.730* 

FORMAT('-.76',4,1) 

-> 

* -0.8* 

FORMAT('3.03',4) 

-> 

* 3.03* 

FORMAT(' - 12.73',,4) 

-> 

*-12.7300* 

FORMAT!' - 12.73’) 

-> 

'-12.73* 

FORMAT('0.000') 

-> 

*0' 

The first three arguments are 

as described above. In 


expt control the exponent part of the result: expp sets the number of 
places to be used for the exponent part, the default being to use as many as 


are needed, expt sets the trigger point for use of exponential notation. If 
the number of places needed for the integer part exceeds expt, exponential 
notation will be used. Likewise, exponential notation will be used if the 
number of places needed for the decimal part exceeds twice expt. The 
default is the current setting of NUMERIC DIGITS. If 0 is specified for 
expt, exponential notation is always used unless the exponent would be 0. 
expp must be less than 10, but there is no limit on the other arguments. If 
0 is specified for the expp field, no exponent will be supplied, and the 
number will be expressed in “simple” form with added zeros as necessary. 
Otherwise, if expp is not large enough to contain the exponent, an error 
results. 





Here are some examples: 


FORMAT!'12345.73',,,2,2) 

-> 

* 1.234573E+04 * 

FORMAT(.' 12345.73' , ,3, ,0) 

-> 

*1.235E+4* 

FORMAT!'1.234573',,3,,0) 

-> 

'1.235* 

FORMAT!'12345.73',,,3,6) 

-> 

’12345.73' 

FORMAT!'1234567e5',,3,0) 

-> 

'123456700000.000 


INDEX 


INDEX (haystack,needle [,start]) 


returns the character position of one string, needle, in another, 
haystack (see also the POS function). If the string needle is not found, 0 
is returned. By default the search starts at the first character of haystack 
(start is of the value 1). This can be overridden by giving a different 
start point, which must be a positive whole number. 

Here are some examples: 
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INDEX( 'abcdef 1 , 

■cd') 

-> 

3 

INDEX ('abcdef' , 

'xd' ) 

-> 

0 

INDEX ('abcdef' , 

'be',3) 

-> 

0 

INDEX( 'abcabc ' , 

'be',3) 

-> 

5 

INDEX ('abcabc', 

'be',6) 

-> 

0 


INSERT 


INSERT (new,target [, [n] [,[ length ] [ ,pad ] ] ]) 


inserts the string new, padded to length length, into the string target 
after the nth character, length and n must be non-negative. If n is 
greater than the length of the target string, padding is added there also. 
The default pad character is a blank. The default value for n is 0, which 
means insert before the beginning of the string. 


Here are some examples: 


INSERT(’ ','abcdef 

’,3) 

-> 

'abc def' 

INSERT('123','abc' 

,5,6) 

-> 

'abc 123 

INSERT('123','abc' 

,5,6,’+') 

-> 

'abc++123+++ 

INSERT('123','abc' 

) 

-> 

'123abc 1 

INSERT('123','abc' 

,,5, ' - ' ) 

-> 

'123—abc' 


JUSTIFY 


JUSTIFY (string .length [ t pad ]) 


formats blank-delimited words in string, by adding pad characters 
between words to justify to both margins. That is, to width length 
(length must be non-negative). The default pad character is a blank. 

string is first normalized as though SPACE (string) had been executed 
(that is, multiple blanks are converted to single blanks, and leading and 
trailing blanks are removed). If length is less than the width of the 
normalized string, the string is then truncated on the right and any trailing 
blank is removed. Extra pad characters are then added evenly from left to 
right to provide the required length, and the blanks between words are 
replaced with the pad character. 

Here are some examples: 


JUSTIFY('The blue 
JUSTIFY('The blue 
JUSTIFY('The blue 
JUSTIFY('The blue 


sky',14) 
sky*,8) 

-> 

-> 

sky*,9) 

-> 

sky',9,'+ 1 ) 

-> 


'The blue sky* 
'The blue* 

'The blue* 

‘ The-M-blue 1 
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LASTPOS 


LASTPOSf needle,hay stack [ ,start\) 


returns the position of the last occurrence of one string, needle, in 
another, haystack. (See also POS.) If the string needle is not found, 0 is 
returned. By default the search starts at the last character of haystack 
(that is, start=LENGTH(string)) and scans backwards. This may be 
overridden by specifying start, the point at which to start the backwards 
scan, start must be a positive whole number. 

Here are some examples: 

LASTPOS(* 1 ,•abc def ghi') -> 8 

LASTPOS( ' 1 , 1 abcdefghi' ) -> 0 

LASTPOS( 1 ', 1 abc def ghi',7) -> 4 


LEFT 


LEFT (string,length[ ,pad ]) 


returns a string of length length containing the left-most length 
characters of string. The string returned is padded with pad characters 
(or truncated) on the right as needed. The default pad character is a blank, 
length must be non-negative. The LEFT function is exactly equivalent to 
SUBSTR(string,1,length [,pad]). 


Here are some examples: 


LEFT('abc 

d' ,8) 

-> 

1 abc 

LEFT('abc 

d',8,'.') 

-> 

1 abc 

LEFT('abc 

def',7) 

-> 

* abc 


LENGTH 


LENGTH (string) 


returns the length of string. 
Here are some examples: 
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LENGTH(’abcdefgh' ) -> 8 
LENGTH('abc defg') -> 8 
LENGTH(••) -> 0 


LINESIZE 


LINESIZE O 


returns the current terminal line width (the point at which the interpreter 
will break lines displayed using the SAY instruction). If this is 
indeterminate, 0 will be returned. 

Note: This is the terminal width as set by the CP TERM LINESIZE 
command (but is limited to the CMS maximum of 130); 0 implies that the 
virtual machine is DISCONNected or that CP TERMINAL LINESIZE OFF 
has been issued. 


MAX 


MA X(number [,number 1. ,) 


returns the largest number from the list specified, formatted according to 
the current setting of NUMERIC DIGITS. Up to ten numbers may be 
specified, although calls to MAX may be nested if more are needed. 


Here are some examples: 


MAX(12,6,7,9) 

-> 

12 

MAX(17.3,19,17.03) 

-> 

19 

MAX(-7,-3,-4.3) 

-> 

-3 

MAX(1,2,3,4,5,6,7,8,9,MAX(10,11,12,13)) 

-> 

13 


MIN 


MIN (number [,number ]. . . ) 


returns the smallest number from the list specified, formatted according to 
the current setting of NUMERIC DIGITS. Up to ten numbers may be 
specified, although calls to MIN may be nested if more are needed. 
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Here are some examples: 


MIN(12,6,7,9) -> 
MIN(17.3,19,17.03) -> 
MIN{-7,-3,-4.3) -> 

6 

17.03 

-7 


OVERLAY 


OVERLAY (new,target [, [n ] [,[length ] [,pad ] ]]> 


overlays the string target, padded or truncated to length length, with the 
string new starting at the nth character. If length is specified it must be 
positive or zero. If n is greater than the length of the target string, padding 
is added there also. The default pad character is a blank, and the default 
value for n is 1. n must be greater than 0. 


Here are some examples: 


OVERLAY(' ','abcdef',3) 

-> 

'ab def* 

OVERLAY(•-•,’abcdef’,3,2) 

-> 

* ab. ef' 

OVERLAY('qq','abed') 

-> 

'qqcd' 

OVERLAY('qq','abed',4) 

-> 

1 abeqq* 

OVERLAY('123','abc',5,6,'+') 

-> 

* abc+123+++ 


POS 


VOS (needle,hay stack [ ,start ]) 


returns the position of one string, needle, in another, haystack. (See 
also the LASTPOS and INDEX functions.) If the string needle is not 
found, 0 is returned. By default the search starts at the first character of 
haystack (that is start is of the value 1). This may be overridden by 
specifying start (which must be a positive whole number), the point at 
which to start the search. 

Here are some examples: 

POS(' day•, 1 Saturday *) -> 6 

POS(*x*,'abc def ghi') -> 0 

POS( 1 ','abc def ghi') -> 4 

POS(• ','abc def ghi',5) -> 8 
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QUEUED 


QUEUED () 


returns the number of lines remaining in the program stack 
(system-provided data queue) at the time when the function is invoked. If 
no lines are remaining, a PULL or PARSE PULL will read from the 
terminal input buffer. If there is no terminal input waiting this causes a 
console read (VM READ). 

Here is an example: 

QUEUED() -> 5 /* Perhaps */ 


RANDOM 


RANDOM ([min] [, [ max ] [ ,seed ] ]) 


returns a pseudo-random non-negative whole number in the range min to 
max inclusive. If only one argument is specified, the range will be from 0 to 
that number. Otherwise, the default values for min and max are 0 and 999 
respectively. A specific seed (which must be a whole number) for the 
random number may be specified as the third argument if repeatable results 
are desired. 


The magnitude of the range (that is, max minus min) may not exceed 100000. 


Here are some examples: 


RANDOM() 

-> 

RANDOM(5,8) 

-> 

RANDOM(,,1983) 

-> 

RANDOM(2) 

-> 


305 

7 

123 /* always */ 

0 


Notes: 

1. To obtain a predictable sequence of pseudo-random numbers, use 
RANDOM a number of times, but only specify a seed the first time. 
For example, to simulate forty throws of a six-sided, unbiased die 

sequence = RANDOM(1,6,12345) /* any number would */ 

/* do for a seed */ 

do 39 

sequence = sequence RANDOM(1,6) 
end 

say sequence 
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The numbers are generated mathematically, using the initial seed, so 
that as far as possible they appear to be random. Running the program 
again will produce the same sequence; using a different initial seed will 
produce a different sequence. If you do not supply a seed, the first time 
RANDOM is called, the microsecond field of the time-of-day clock will 
be used as the seed; and hence your program will give different results 
each time it is run. 

2. The random number generator is global for an entire program - the 
current seed is not saved across internal routine calls. 


REVERSE 


REVERSE (string) 


returns string, swapped end for end. 

Here are some examples: 

REVERSE( 1 ABC. *) -> 1 .cBA ' 

REVERSE('XYZ ’) -> ' ZYX 1 


RIGHT 


RIGHT (string,length [ % pad ]) 


returns a string of length length containing the right-most length 
characters of string. The string returned is padded with pad characters 
(or truncated) on the left as needed. The default pad character is a blank, 
length must be non-negative. 


Here are some examples: 


RIGHT('abc d',8) 

-> 

’ abc d’ 

RIGHT('abc def',5) 

-> 

*c def' 

RIGHT('12',5,'O') 

-> 

1 00012 1 
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SIGN 


SIGN (number) 


number is rounded according to the current setting of NUMERIC DIGITS, 
and then: 

if the result is: the value returned is: 

<0 -1 

= 0 0 

>0 1 


Here are some examples: 

SIGN(*12.3') -> 1 

SIGN( 1 -0.307') -> -1 

SIGN(0.0) -> 0 


SOURCELINE 


SOURCELINE ([n]) 


If n is omitted, returns the line number of the final line in the source file. 

If n is given, the nth line in the source file is returned, n must be a 
positive whole number, and must not exceed the number of the final line in 
the source file. 

Here are some examples: 

SOURCELINE() -> 10 

SOURCELINE(1) -> 1 /* This is a 10-line program */• 


SPACE 


SPACE (string [, [ n][ ,pad ]]) 


formats the blank-delimited words in string with n pad characters 
between each word, n must be non-negative. If it is 0, all blanks are 
removed. Leading and trailing blanks are always removed. The default for 
n is 1, and the default pad character is a blank. 
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Here are some examples: 


SPACE('abc def 

') 

-> 

'abc def* 

SPACE(' abc def' 

,3) 

-> 

* abc def 

SPACE('abc def 

M) 

-> 

* abc def * 

SPACE('abc def 

' ,0) 

-> 

'abcdef * 

SPACE('abc def 

' , 2 ,'+') 

-> 

'abc++def 1 


STORAGE 


This is part of the RXSYSFN package. See page 116. 


STRIP 


STRIP (string [,[ option ] [ t char]]) 


removes characters from string based on the option specified. Valid 
optionss (of which only the capitalized letter is significant, all others are 
ignored) are: 

Leading removes leading characters from string 
Trailing removes trailing characters from string 

Both removes both leading and trailing characters from string. The 
default is B. 

The third argument, char, specifies the character to be removed, with the 
default being a blank. If given, char must be exactly one character long. 


Here are some examples: 


STRIP( ’ 

ab c 

') 

-> 

* ab c 

STRIP(' 

ab c 

' ,'L') 

-> 

'ab c 

STRIP( ' 

ab c 

’ ,'t' ) 

-> 

' ab 

STRIP(’12.7000' 

,,0) 

-> 

* 12.7 

STRIP('0012.700 

' ,,0) 

-> 

1 12.7 


SUBSTR 


SUBSTR (string,n[,[length][ t pad ]]) 


returns the substring of string that begins at the nth character, and is of 
length length, padded with pad if necessary, n must be a positive whole 
number. 
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If length is omitted it defaults to be the rest of the string. The default pad 
character is a blank. 

Here are some examples: 


SUBSTR('abc' 

,2) 

-> 

•be* 

SUBSTR('abc' 

,2,4) 

-> 

'be 

SUBSTR('abc' 

,2,6,'.') 

-> 

'be. . 


Note: In some situations the positional (numeric) patterns of parsing 
templates are more convenient for selecting substrings, especially if more 
than one substring is to be extracted from a string. 


SUBWORD 


SUBWORD (string,n [,length ]) 


returns the substring of string that starts at the nth word, and is of 
length length blank-delimited words, n must be a positive whole number. 
If length is omitted, it defaults to be the remaining words in string. The 
returned string will never have leading or trailing blanks, but will include 
all blanks between the selected words. 


Here are some examples: 


SUBWORD('Now 

is 

the 

time' , 2 , 2 ) 

-> 

'is the' 

SUBWORD('Now 

is 

the 

time',3) 

-> 

'the time 

SUBWORD('Now 

is 

the 

time ',5) 

-> 

i i 


SYMBOL 


SYMBOL fna/ne) 


If name is not a valid REXX symbol, BAD is returned. If it is the name of a 
variable (that is, a symbol that has been assigned a value), VAR is returned. 
Otherwise LIT is returned, which indicates that it is either a constant 
symbol or a symbol that has not yet been assigned a value (that is, a 
Literal). 

Like symbols appearing normally in REXX expressions, lowercase 
characters in the name will be translated to uppercase and substitution in a 
compound name will occur if possible. 
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Note: Normally name should be specified in quotes (or derived from an 
expression), to prevent substitution by its value before it is passed to the 
function. 

Here are some examples: 

/*■ following: Drop A. 3; J=3 */ 


SYMBOL('J 1 

) 

-> 

VAR 






SYMBOL(J) 


-> 

LIT 

/* 

has 

tested 

"3" 

*/ 

SYMBOL('a. 

j') 

-> 

LIT 

/* 

has 

tested 

"A. 3** 

v 

SYMBOL(2) 


-> 

LIT 

/* 

a constant 

symbol 

V 

SYMBOL('*' 

) 

-> 

BAD 

/* 

not 

a valid 

symbol 

V 


TIME 



by default returns the local time in the 24-hour clock format: hh:mm:ss: 

(hours, minutes, and seconds); for example, '04:41:37’. 

The following options (only the capitalized letter is significant, all others 

are ignored) may be supplied to obtain alternative formats, or to gain access 

to the elapsed time calculator. 

Elapsed returns sssssssss.uuuuuu, the number of seconds.microseconds 
since the elapsed time clock was started or reset (see below). 

The number will have no leading zeros, and is not affected by the 
setting of NUMERIC DIGITS. 

Hours returns number of hours since midnight in the format: hh (no 
leading zeros). 

Long returns time in the format: hh:mm:ss.uuuuuu (uuuuuu is the 
fraction of seconds, in microseconds). 

Minutes returns number of minutes since midnight in the format: mmmm 
(no leading zeros). 

Reset returns sssssssss.uuuuuu, the number of seconds.microseconds 

since the elapsed time clock was started or reset (see below), and 
also resets the elapsed time clock to zero. The number will have 
no leading zeros, and is not affected by the setting of NUMERIC 
DIGITS. 

Second returns number of seconds since midnight in the format: sssss (no 
leading zeros). 

Here are some examples: 
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TIME CL’) 

-> 

TIME() 

-> 

TIME{'H') 

-> 

TIME('M') 

-> 

TIME('S’) 

-> 


16:54:22.123456 

16:54:22 

16 

1014 

60862 /* 22 + 


/* Perhaps */ 

/* 54 + 60*16 */ 
60*(54+60*16) */ 


The elapsed time clock: 


The elapsed time clock may be used for measuring real time intervals. On 
the first call to the elapsed time clock, the clock is started, and both 
TIME (' E *) and TIME (• R *) will return 0. 

The clock is saved across internal routine calls, which is to say that an 
internal routine will inherit the time clock started by its caller, but if it 
should reset the clock any timing being done by the caller will not be 
affected. An example of the elapsed time calculator: 


time( 1 E 1 ) -> 
/* pause of one 
time('E') -> 
/* pause of one 
time('R*) -> 
/* pause of one 
timeC'R') -> 


0 /* 
second here */ 
1.002345 /* 

second here */ 
2.004690 /* 

second here */ 
1.002345 /* 


The first call */ 
or thereabouts */ 
or thereabouts */ 
or thereabouts */ 


Note: See the note under DATE about consistency of times within a single 
expression. The elapsed time clock is synchronized to the other calls to 
TIME and DATE, so multiple calls to the elapsed time clock in a single 
expression will always return the same result. For the same reason, the 
interval between two normal TIME/DATE results may be calculated exactly 
using the elapsed time clock. 


Implementation maximum: Should the number of seconds in the elapsed 
time exceed nine digits (equivalent to over 31.6 years), an error will result. 


TRACE 


TRACE ([option] ) 


returns trace actions currently in effect. 

If option is supplied, it must be one of the valid prefixes (? or !) and/or 
alphabetic character options (A, C, E, I, L, N, O, R, or S) associated with 
the TRACE instruction. (See the TRACE instruction, on page 62, for full 
details.) The function uses option to alter the effective trace action (like, 
command inhibition, tracing Labels, etc.). Unlike the TRACE instruction, 
the TRACE function alters the trace action even if interactive debug is 
active. 

Unlike the TRACE instruction, option cannot be a number. 
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Here are some examples: 


TRACE() 

-> 

' ?R' 

/* 

maybe */ 


TRACE(’O') 

-> 

1 ?R 1 

/* 

also sets tracing off 

*/ 

TRACE( ' 71 ') 

-> 

’O’ 

/* 

now in interactive debug 

V 


TRANSLATE 


TRANSLATE (string [, [tableo ][>[tablei][ ,pad ] ] ]) 


Translates characters in string to be other characters, or may be used to 
reorder characters in a string. If neither translate table is given, string is 
simply translated to uppercase, tableo is the output table and tab lei is 
the input translate table (the default is XRANGE (* 00 1 x, 1 FF 1 x)). The 
output table defaults to the null string, and is padded with pad or truncated 
as necessary. The default pad is a blank. The tables may be of any length: 
the first occurrence of a character in the input table is the one that is used 
if there are duplicates. 


Here are some examples: 


TRANSLATE('abcdef') 


-> 

1 ABCDEF 1 


TRANSLATE('abbc'b' 

) 

-> 

'aSSc* 


TRANSLATE('abcdef','12', 

'ec' ) 

-> 

1 ab2dlf 1 


TRANSLATE('abcdef ',' 12 ', 

•abed','.’) 

-> 

*12..ef 1 


TRANSLATE('4123','abed', 

'1234') 

-> 

* dabc * 



Note: The last example shows how the TRANSLATE function may be used 
to reorder the characters in a string. In the example, any 4-character string 
could be specified as the second argument and its last character would be 
moved to the beginning of the string. 


TRUNC 


TRUNC (number [,n]) 


returns the integer part of number, and n decimal places. The default n is 
zero, number is truncated to n decimal places (or trailing zeros are added 
if needed to make up the specified length). Exponential form will not be 
used. 

Here are some examples: 
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TRUNC(12.3) 

-> 

12 

TRUNC(127.09782,3) 

-> 

127.097 

TRUNC(127.1,3) 

-> 

127.100 

TRUNC(127,2) 

-> 

127.00 


Note: number will be rounded according to the current setting of 
NUMERIC DIGITS if necessary before being processed by the function. 


USERID 


USERID ( ) 


returns the system-defined User Identifier. 
USERID() -> 'ARTHUR' /* Maybe */ 


VALUE 


VALUE (name) 


The value of the symbol name is returned. Like symbols appearing 
normally in REXX expressions, lowercase characters in name will be 
translated to uppercase and substitution in a compound name will occur if 
possible, name must be a valid REXX symbol, or an error results. 


Here are some examples: 


/* following: 
VALUE(’fred’) 

Drop A3; 

A33= 

7; J=3; fred= 

= 'J' */ 

-> 

' J' 

/* looks up 

"FRED" */ 

VALUE(fred) 

-> 

'3' 

/* looks up 

"J" */ 

VALUE('a'j) 

-> 

'A3 

i 


VALUE('a’j| | j ) 

-> 

'7' 




Note: The VALUE function is typically used when a variable contains the 
name of another variable, or a name is constructed dynamically; for 
example, VALUE ( ' LINE ' index) . It is not useful to wholly specify name as 
a quoted string, since the symbol is then constant and so the whole function 
call could be replaced directly by the data between the quotes. (For 
example, fred=VALUE( ' j ' ) is always identical to the assignment fred=j). 
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VERIFY 


VERIFY (string reference [,[ match ] [ ,stort ] ]) 


Verifies that string is composed only of characters from reference, by 
returning the position of the first character in string that is not also in 
reference. If all the characters were found in reference, 0 is returned. 

If match is specified, the position of the first character in string that is in 
reference is returned, or 0 if none of reference is returned, or 0 if none 
of the characters were found. 

The default for start is 1, thus, the search starts at the first character of 
string. This can be overridden by giving a different start point, which 
must be a positive whole number. 

The third argument may be any expression that results in a string starting 
with M or m. 

If string is null, the function returns 0, regardless of the value of the third 
argument. Similarly if start is greater than LENGTH(string), 0 is 
returned. 


Here are some examples: 


VERIFY('123',’1234567890') 

-> 

0 

VERIFY('1Z3 1 ,'1234567890') 

-> 

2 

VERIFY('AB4T',’1234567890','M') 

-> 

3 

VERIFY('1P3Q4','1234567890',,3) 

-> 

4 

VERIFY('AB3CD5','1234567890','M',4) 

-> 

6 


WORD 


WORD (string,n) 


returns the nth blank-delimited word in string, n must be a positive 
whole number. If there are less than n words in string, the null string is 
returned. This function is exactly equivalent to SUBWORD(string,n, 1). 
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Here are some examples: 

WORD( 1 Now is the time',3) -> 'the' 

WORD(’Now is the time’,5) -> 11 

WORDINDEX 



returns the position of the nth blank-delimited word in string, n must be 
a positive whole number. If there are not n words in the string, 0 is 
returned. 

Here are some examples: 

WORDINDEX(’Now is the time',3) -> 8 

WORDINDEX('Now is the time',6) -> 0 

WORDLENGTH 



returns the length of the nth blank-delimited word in string, n must be a 
positive whole number. If there are not n words in the string, 0 is returned. 

Here are some examples: 

WORDLENGTH('Now is the time',2) -> 2 

WORDLENGTH('Now comes the time',2) -> 5 

WORDLENGTH('Now is the time',6) -> 0 

WORDS 



returns the number of blank-delimited words in string. 

Here are some examples: 

WORDS('Now is the time') -> 4 

WORDS(' ') -> 0 
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XRANGE 


XRANGEf [star* ] [,end]) 


returns a string of all one byte codes between and including the values 
start and end. start defaults to ‘00’x, and end defaults to ‘FF’x. If 
start is greater than end, the values will wrap from X‘FF* to X‘00’. 
start and end must be single characters. 


Here are some examples: 


XRANGE('a',' 

f ' ) 

-> 

XRANGE('03 1 x 

' 07 ' x) 

«> 

XRANGE(,’04 ’ 

x) 

-> 

XRANGE(’i 1 ,' 

j ’ ) 

-> 

XRANGE('FE 1 x 

1 02 1 x) 

-> 


1 abcdef 1 
1 0304050607 1 x 
’ 0001020304 1 x 
’ 898A8B8C8D8E8F9091' x 
1 FEFF000102 1 x 


X2C 


X2C (hex-string) 


Hexadecimal to Character. Converts hex-string (a string of hexadecimal 
characters) to character, hex-string will be padded with a leading 0 if 
necessary to make an even number of hexadecimal digits. 

Blanks may optionally be added (at byte boundaries only, not leading or 
trailing) to aid readability; they are ignored. 


Here are some examples: 


X2C( 1 F7F2 A2') 

-> 

* 72s * 

X2C('F7f2a2') 

-> 

* 72s' 

X2C('F') 

-> 

1 OF 1 x 


X2D 


X2D (hex-string [,n]> 


Hexadecimal to Decimal. Converts hex-string (a string of hexadecimal 
characters) to decimal. If the result cannot be expressed as a whole 
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number, an error results. That is, the result must have no more than 
NUMERIC DIGITS digits. 

hex-string may be the null string. 


If n is not specified, hex-string is taken to be an unsigned number. 


Here are some examples: 


X2D(’0E 1 

1 ) 

-> 

14 

X2D(’81' 

' ) 

-> 

129 

X2D('F81 1 ) 

-> 

3969 

X2D(’FF81') 

-> 

65409 

X2D('c6 

fO'X) 

-> 

240 


If n is specified, hex-string is taken to represent a two's complement 
number expressed as n hexadecimal characters, and is converted to a REXX 
whole number that may, therefore, be negative. If n is 0, 0 is always 
returned. 


If necessary, hex-string is padded on the left with 0 characters (note, not 
“sign-extended”), or truncated on the left, to length n characters; (that is, 
as though RIGHT (string, n, ’ 0 ’ ) had been executed.) 


Here are some examples: 


X2D(’81’ , 2 ) 

-> 

-127 

X2D('81',4) 

-> 

129 

X2D('F081',4) 

-> 

-3967 

X2D( 1 F081 1 ,3) 

-> 

129 

X2D('F081',2) 

-> 

-127 

X2D('F081 1 ,1) 

-> 

1 

X2D('0031',0) 

-> 

0 


Implementation maximum: The input string may not have more than 
500 hexadecimal characters that will be significant in forming the final 
result. Leading sign characters (0 and F) do not count towards this total. 


Function Packages 

If an external function or subroutine is called, which is in a function 
package known to the interpreter, the interpreter will automatically load 
the function package before calling the function. To the general user 
with adequate virtual storage, the functions that have been provided in 
packages seem like ordinary built-in functions. 

The interpreter searches each of the function packages named below, if it is 
installed. 

RXUSERFN This is the name of a package that the general user may 

write. The package would be written in assembler language 
and would contain a number of functions and their common 
subroutines. For a description of assembler language 
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interfaces to the interpreter, see page 149. For a description 
of function packages, see page 157. 

RXLOCFN Similarly, this is the name of a package that system support 
people at your installation may write. 

RXSYSFN This is the name of the additional function package that can 
be created and used by both system support personnel and 
general users. 

The interpreter will search for a function in the packages in the order given 

above. See page 71 for the complete search order. 


VM Functions 


The following are additional external functions provided in the VM/SP 
environment: CMSFLAG returns the setting of certain indicators, DIAG 
and DIAGRC can be used to issue special commands to CP, and STORAGE 
can be used to inspect or alter the main storage of your virtual machine. 


CMSFLAG(flag) 


CMSFLAG (flag) 


returns the value 1 or 0 depending on the setting of flag. Specify any one 
of the following flag names. (No abbreviations are allowed). For more 
information on the commands listed below, refer to the VM/SP CMS 
Macros and Functions Reference , SC24-5284. 

ABBREV returns 1 if, when searching the synonym tables, truncations will 
be accepted; else returns 0. Set by SET ABBREV ON; reset by 
SET ABBREV OFF. 

AUTOREAD 

returns 1 if a console read is to be issued immediately after 
command execution; else returns 0. Set by SET AUTOREAD 
ON; reset by SET AUTOREAD OFF. 

CMSTYPE returns 1 if console output is to be displayed (or typed) within an 
EXEC; returns 0 if console output is to be suppressed. Set by 
SET CMSTYPE RT or the immediate command RT. Reset by 
SET CMSTYPE HT or the immediate command HT. 

DOS returns 1 if your virtual machine is in the DOS environment; else 

returns 0. Set by SET DOS ON; reset by SET DOS OFF. 
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EXECTRAC 

returns 1 if EXEC Tracing is turned on (equivalent to the 
TRACE prefix option else returns 0. Set by SET 
EXECTRAC ON or the immediate command TS. Reset by SET 
EXECTRAC OFF or the immediate command TE. (See page 120.) 

IMPCP returns 1 if commands that CMS does not recognize are to be 
passed to CP; else returns 0. Set by SET IMPCP ON; Reset by 
SET IMPCP OFF. Applies to commands issued from the CMS 
command line and also to REXX clauses that are commands to 
the ‘CMS’ environment. 

IMPEX returns 1 if EXECs may be invoked by filename; else returns 0. 

Set by SET IMPEX ON; Reset by SET IMPEX OFF. Applies to 
commands issued from the CMS command line and also to REXX 
clauses that are commands to the ‘CMS* environment. 

PROTECT returns 1 if the CMS nucleus is storage-protected; else returns 0. 
Set by SET PROTECT ON; Reset by SET PROTECT OFF. 

RELPAGE returns 1 if pages are to be released after certain commands have 
completed execution; else returns 0. Set by SET RELPAGE ON; 
Reset by SET RELPAGE OFF. 

SUBSET returns 1 if you are in the CMS subset; else returns 0. Set by 
SUBSET (this command is issued by some editors); Reset by 
RETURN. (For details, refer to “CMS subset” in the reference 
manual of the editor you are using). 


DIAG 


DIAG(>i[ ? ] [ f data ][,data ]. . .) 


communicates with CP via a dummy DIAGNOSE instruction and returns 
data as a character string. (This interface is described in the discussion on 
the DIAGNOSE Instruction in the VM/SP System Facilities for 
Programming , SC24-5288.) 

n is the hexadecimal diagnose code to be executed. Leading zeros can be 
omitted. Also, the use of quotes is optional. ? indicates that diagnostic 
messages are to be displayed if appropriate, data is dependent upon the 
specific diagnose code being executed; it is generally the input data for the 
given diagnose. 

(Warning: A DIAGNOSE instruction with invalid parameters may in some 
cases result in a specification exception or a protection exception.) 
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The data returned is in binary format; that is, it is precisely the data 
returned by the DIAGNOSE; no conversion is performed. 

Note: The REXX built-in functions C2X and C2D are invaluable for 
converting the returned data. Samples of the use of these functions are 
included in the descriptions of Diagnoses ‘0C’ and W. 

Codes are the same as for DIAGRC (below). 


DIAGRC 


DIAGRC(h[ ? ] [,data] [,data. . .]) 


is identical to the DIAG function where: 


n is the hexadecimal diagnose code to be executed. Leading zeros can be 
omitted. Also, the use of quotes is optional. ? indicates that diagnostic 
messages are to be displayed if appropriate, data is dependent upon the 
specific diagnose code being executed; it is generally the input data for the 
given diagnose. 


In contrast to the DIAG function the data returned in this function is 
prefixed with: 


Character 

position Contents 


I to 9 
10 

II 

12 to 16 


Return code from CP 
a blank 

Condition code from CP 
five blanks 


The input and the returned data for each supported diagnose are: 
DIAG (00) — Store Extended-Identification Code 


DIAGRC(00) 

The value returned is a string, at least 40 characters in length, 
depending on the level of nesting of VM/SP. Ordinarily 40 bytes of 
data are returned. 


DIAG (08 , cpcommand [ , sizebuf ] ) — Virtual Console Function 

DIAGRC ( 08 ,cpcommand?lbrk.,sizebuf]) 

Input is cpcommand (CP command) to be issued (240 bytes maximum), 
followed (optionally) by a third argument, sizebuf, that specifies the 
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size (in bytes) of the buffer that will contain the result. This buffer 
size must be a non-negative whole number; the default is 4096. 

Any command response is returned as the function value. If the 
response contains multiple lines, they are delimited in the returned 
data by the character X‘15\ 


Note that the command is passed to CP without any translation to 
uppercase. Thus commands specified as a quoted string (a good idea) 
must be in uppercase or CP will not recognize them. For example: 


Diag(8,* query rdr all') / 

/ 

/ 

Diag(8,query rdr all) / 

/ 

/ 

/ 

/ 

Diag(8,* QUERY RDR ALL') / 


DIAG ( 0C ) — Pseudo Timer 


fails because CP has no */ 
"query** command (only */ 
"QUERY"). */ 

ordinarily works, but will*/ 
fail if "query", "rdr" or */ 
"all" are variables that */ 
have been assigned values */ 
other than their own names*/ 

is the best and safest. */ 


DIAGRC(OC) 


The value returned is a 32 byte string containing the date, time, 
virtual time used, and total time used. 

For example, to display the virtual time: 

Say ’Virtual time =* c2x(substr(diag(*C*),17,8)) *(Hex)' 

/* This results in a display of the form */ 

Virtual time = 00000000004BF959 (Hex) 


The virtual time may be displayed as a decimal value by using the 
C2D function: 

Say *Virtual time =* c2d(substr(diag(*C*),17,8)) 

/* This results in a display of the form */ 

Virtual time = 4979033 

DIAG (14 , acronym, rdrvaddr , addvals) — Input File Manipulation 
DIAGRC(14,acronym,rdrvaddr,addvals) 

Where: 


1. acronym is one of those as described below. 

2. r drvaddr is the address of the virtual reader. 
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3. addvals are one or more additional and sometimes optional 
values associated with a given acronym. Acronym descriptions 
(below) describe any additional, associated values as well. 

The value returned is: 

Character 

position Contents 

1 Condition code 

2 a blank 

3 to 6 Four bytes from register y -+1 

7 to 8 two blanks 

9 onwards a return string (if any) whose length and 

content depend upon the function being 
performed. 

Note: The PARSE instruction may be used to assign these operands 
to suitable variables, as in the examples given below. 

Acronym Descriptions: 

RNSB, rdrvaddr — Read Next Spool Buffer (data record) 

There are no additional values associated with this acronym. 

The return string is the 4096 byte spool file buffer. For example, 

Parse value diag(14,* RNSB','00C•), 

with cc 2 . 3 Rypl 7 . 9 buffer 

/* will read the next spool buffer from the */ 

/* card reader at address X'OOC* and assign: */ 

/* CC = the condition code */ 

/* RYP1 = the contents of register y+1 */ 

/* BUFFER = the 4096 byte spool buffer */ 

RNPRSFB, rdrvaddrffl , readnum" — Read Next PRint Spool File Block 

readnum may be used to specify the number of doublewords of the 
spool file block to be read. (See item 3 of “Notes on Diagnose 
X'14'” on page 112.) 

The return string is the next spool file block of type PRT. Thus 
to read the next spool file block of type PRT from device X‘00C’: 

Parse value diag(14RNPRSFB ' 00C*,15), 
with cc 2 . 3 Rypl 7 . 9 SFB 

/* will read the next print spool file block from */ 
/* the card reader at address X'OOC* and assign: */ 


/* CC = the condition code */ 
/* RYP1 = the contents of register y+1 */ 
/* SFB = the 120 byte spool file block */ 
/* (or 15 doublewords) */ 
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RNPUSFB, rdrvaddrffl,readnum" — Read Next PUnch Spool File 
Block 

readnum may be used to specify the number of doublewords of the 
spool file block to be read. (See item 3 of “Notes on Diagnose 
X‘14’” on page 112.) 

The return string is the next spool file block of type PUN. 

Thus to read the next spool file block of type PUN from device 
X‘00C’: 


Parse value diag(14, 1 RNPUSFB 1 , 1 00C 1 ,15), 
with cc 2 . 3 Rypl 7 . 9 SFB 

/* will read the next punch spool file block from */ 
/* the card reader at address X*OOC* and assign: */ 
/* CC = the condition code */ 

/* RYP1 = the contents of register y+1 */ 

/* SFB = the 120 byte spool file block */ 

SF,rdrvaddr, spf ileid — Select a File for processing 

spf ileid specifies the spool file id. 

There is no return string other than the condition code and Ry +1 
value. 

Thus to select spool file number 8159 for processing from device 
X'OOCT: 

Parse value diag(14,'SF', 1 00C•,8159), 
with cc 2 . 3 Rypl 7 


/* will select a file for processing from the */ 
/* card reader at address X'OOC' and assign: */ 
/* CC = the condition code */ 
/* RYP1 = the contents of register y+1 */ 


RPF , rdrvaddr, newcopy — RePeat active File nn times 
newcopy specifies the new copy count. 

There is no return string other than the condition code and Ry + 1 
value. 

Thus to change the copy count for the active file on device yOOC’ 
to 5: 

Parse value diag(14,*RPF', '00C*,5), 
with cc 2 . 3 Rypl 7 


/* will repeat active file 5 times on the */ 
/* card reader at address X'OOC* and assign: */ 
/* CC = the condition code */ 
/* RYP1 = the contents of register y+1 */ 
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RSF, rdrvaddr — ReStart active File at beginning 

There are no additional values associated with this acronym. 

The return string is the first 4096 byte spool file buffer. 

Thus to reset the active file on device X‘00C’ to the beginning and 
read the first spool buffer: 

Parse value diag(14,'RSF', 1 OOC 1 ), 

with cc 2 . 3 Rypl 7 . 9 buffer 

BS , rdrvaddr — BackSpace one record 

There are no additional values associated with this acronym. 

The return string is the 4096 byte spool file buffer. 

Thus to read the previous spool buffer from the file active on 
device X‘00C’: 

Parse value diag(14,'BS*, 1 00C 1 ), 

with cc 2 . 3 Rypl 7 . 9 buffer 

/* will read the previous spool file buffer from */ 

/* the card reader at address X'OOC* and assign: */ 

/* CC = the condition code */ 

/* RYP1 = the contents of register y+1 */ 

/* BUFFER = the first 4096 bytes of the file */ 

RNMNSFB , rdrvaddrffl, readnum" — Read Next MoNitor Spool File 
Block 

readnum may be used to specify the number of doublewords of the 
spool file block to be read. (See item 3 of “Notes on Diagnose 
X‘14’” on page 112.) 

The return string is the spool file block. 

Thus to read the next monitor spool file block from device X^OC’: 

Parse value diag(14, 'RNMNSFB 1 ,'00C' ,15), 
with cc 2 . 3 Rypl 7 . 9 SFB 

/* will read the next monitor spool file block from */ 


/* the card reader at address X'OOC* and assign: */ 
/* CC = the condition code */ 
/* RYP1 = the contents of register y+1 */ 
/* SFB = the 120 byte spool file block */ 


RNMNSB , rdrvaddr — Read Next MoNitor Spool Buffer 

There are no additional values associated with this acronym. 
The return string is the 4096 byte spool file buffer. 
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Thus to read the next monitor spool buffer from the card reader at 
address X‘00C’: 

Parse value diag(14 , 9 RNMNSB*,'00C 1 ), 

with cc 2 . 3 Rypl 7 . 9 buffer 

/* will read the next monitor spool file buffer */ 


/* from the card reader at address X'OOC* and */ 
/* assign: */ 
/* CC = the condition code */ 
/* RYP1 = the contents of register y+1 */ 
/* BUFFER = the 4096 byte spool buffer */ 


RSFD , spf ilenum[ ,numwords [ ,3800] ] — Retrieve Subsequent File 
Descriptor 

spf ilenum specifies the spool file number. The optional 
numwords specifies the number of doublewords of spool file block 
data to be returned. (See item 3 of “Notes on Diagnose X'14'” on 
page 112.) 3800, also optional, may be specified to cause 40 

bytes of 3800 information to be included between the spool file 
block and tag. 

Thus to obtain information about the next spool file without 
regard to type, class, etc.: 

Parse value diag(14,* RSFD 1 ,0,15,3800), 

with cc 2 . 3 Rypl 7 . 9 SFB, 

129 data__3800 169 . 181 tag 


/* will read the spool file block */ 
/* from the card reader at address X'OOC* and */ 
/* assign: */ 
/* CC = the condition code */ 
/* RYP1 = the contents of register y+1 */ 
/* SFB = the 120 byte spool file block */ 
/* DATA_3800 = the 3800 data */ 
/* TAG = the tag data */ 


(Refer to Notes 1 and 2 below for additional information.) 

RSFDNPR, n [, numwords [, 3800] ] — Retrieve Subsequent File 
Descriptor Not Previously Retrieved 

n is either 0 (to retrieve subsequent file descriptor not previously 
retrieved), or 1 (to reset the previously retrieved flags for all the 
file descriptors; then retrieve the first file descriptor). The 
optional numwords specifies the number of doublewords of spool 
file block data to be returned. (See item 3 of “Notes on Diagnose 
X'14'” below.) 3800 also optional, may be specified to cause 40 
bytes of 3800 information to be included between the spool file 
block and the tag. 
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Thus to obtain information about the next not previously 
retrieved file without regard to type, class etc.: 

Parse value diag(14,’RSFDNPR',0,15), 

with cc 2 . 3 Rypl 7 . 9 SFB 129 . 181 tag 


/* will read the spool file block */ 
/* from the card reader at address X’OOC' and */ 
/* assign: */ 
/* CC = the condition code */ 
/* RYP1 = the contents of register y+1 */ 
/* SFB = the 120 byte spool file block */ 
/* TAG = the tag data */ 


(Refer to Notes 1 and 2 below for additional information.) 

Notes on Diagnose X 4 14’ 

1. Because only one bit is provided to indicate that the length of 
return data is being explicitly stated and that 3800 data is being 
requested, if either is specified (on RSFD or RSFDNPR calls), 40 
bytes of 3800 data are returned. 

2. RSFD and RSFDNPR will wait for a file being used by a system 
function. If, however, the file does not become available in the 
250 millisecond time limit, the function will return a null string 
for DIAG, normal return code information for DIAGRC. For a 
discussion of possible causes for this condition, see the notes on 
“DIAGNOSE Code X'14'” in the VM/SP System Facilities for 
Programming , SC24-5288. 

3. For RNPRSFB, RNPUSFB, RMNSFB, RSFD, and RSFDNPR, the 
default number of doublewords of spool file block is 13; however, 
the length of the spool file in the current release of VM/SP is 15 
doublewords (120 bytes). 

DIAG ( 2 4, devaddr) — Device Type and Features 
DIAGRC(24, devaddr) 

The input, devaddr, is the device address (or -1 for virtual console). 


§ 
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The value returned is a 13-byte string of virtual and real device 
information: 


Position 
1 through 4 

5 through 8 

9 through 12 

13 


Contents 

Virtual device information from 
Register y 

Real device information from Register 

y+i 

(if -1 was specified) virtual console 
information from Register x 
Condition code 


DIAG(5C,editstring[,headerlen] ) — Error Message Editing 


DIAGRC(5C,editstring[Readerlen]) 


editstring, is a string to be edited according to the current EMSG 
setting, header len is the length of the header used for the editing. 
If headerlen is not specified, the default length is 10. The header len 
may not be longer than editstring. 

The value returned is the edited message, which will be a null string, 
the message code, the message text, or the entire input string, 
depending on the EMSG setting. 

DIAG ( 60 ) — Determine Virtual Storage Size 

DIAGRC(60) 


The value returned is the 4 byte virtual storage size. 
This value may be displayed in hexadecimal via: 


Say 'Virtual storage = ' c2x(Diag(60)) 
resulting (for example) in display of the line: 


Virtual storage = 00100000 

Alternatively, storage size may be expressed in terms of K via: 

Say 'Virtual storage =' x2d(c2x(diag(60)))/1024'K' 
resulting (for example) in display of the line: 

Virtual storage = 512K 

Comparisons of the value returned may be done in hexadecimal: 
Say diag(60) > '00100000'x 


Part 3: Functions 113 




Functions 


m 


results in display of 1 for virtual machines greater than 1M 
in size and 0 for those 1M or less. 

The same comparison may be expressed in terms of megabytes: 

Say x2d(c2x(diag(60)))/(1024*1024) > 1 
with the same results. 

DIAG ( 64, subcode, name ) — Find, Load, or Purge a Named Segment 
DIAGRC (64,subcode,name ) 

The input, subcode, is a 1-character code indicating the subfunction 
to be performed, followed by a third argument, name, the name of the 
segment. 

The value returned is a 9-byte string consisting of the returned Rx and 
Ry values, and a single byte condition code. 

The subfunction codes are: 

S Load the named segment in shared mode. 

L Load the named segment in non-shared mode. 

P Release the named segment from virtual storage. 

F Find starting address of the named segment. 

For example, to find the load address of the segment SPFSEG and 
display the starting and ending addresses and the condition code: 

spfsegaddr=diag(64,*F','SPFSEG') 

Say 'Start:' c2x(substr(spfsegaddr,2,3)), 

' End:' c2x(substr(spfsegaddr,6,3)), 

' CC:' substr(spfsegaddr,9,1) 

/* which displays: 

Start: 230000 End: 24FFFF CC: 0 */ 

indicating that the segment loads from 230000 to 24FFFF, and is 
already loaded (cc = 0). 

Warning: The L and S functions should be used with caution. It is 
the coder's responsibility to ensure that the loaded segment will not 
overlap virtual storage (see diag 60 above). CP will load a segment 
in the middle of your virtual storage if requested, so code carefully. 

DIAG (8C) — Access Certain Device Dependent Information 

DIAGRC(8C) 

The value returned is a string no larger than 502 bytes. The string 
contains device-dependent information about the device (the virtual 
console). If the virtual machine is disconnected or the virtual console 
is a TTY device, then the returned string is null. 
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The value returned is: 

Byte Contents 


0 

flags: 



X'01' 

14-bit addressing is available 


X'20' 

programmed symbol sets are 
available 


X'40' 

device has extended highlighting 


X'80' 

device has extended color 

1 

number of partitions 

2-3 

number of columns on the terminal 

4-5 

number of rows on the terminal 

6-n, 

information returned to CP by the initial 

n<502 

Write Structured Field Query Reply 


DIAG(C8, langid) — SET CP's language 

The function value returned is a five byte string containing the langid 
that CP set. 

DIAGRC(C8,langid) 

The diagrc value returned is a sixteen byte string composed of nine 
characters for the return code, a blank, and six characters for the 
condition code. 

If this DIAGNOSE code is issued from an exec and CMS is on a back 
level version of CP, error message DMSREX475E (Incorrect call 
to routine) is issued and the exec will terminate. 


DIAG ( CC, langid, addr ) — SAVE CP's language repository at address 
addr 

The value returned for the DIAG function is a null string, addr 
must be on a page boundary. 

DIAGRC(CC,langid,addr) 

The diagrc value returned is a sixteen byte string composed of nine 
characters for the return code, a blank, and six characters for the 
condition code. 

If this DIAGNOSE code is issued from an exec and CMS is on a back 
level version of CP, error message DMSREX475E (Incorrect calx 
to routine) is issued and the exec will terminate. 

Message DMSREX475E also results if an unauthorized userid tries to 
issue DIAGNOSE code X'CC'. Return code 20040 is set. 
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STORAGE 


STORAGE ([ address [, [length ] [,data ] ] ]) 


returns the current virtual machine size expressed as a hexadecimal string 
if no arguments are specified. Otherwise, returns length bytes from the 
user's memory starting at address, length is in decimal; the default is 1 
byte, address is a hexadecimal number. 

If data is specified, after the “old” value has been retrieved, storage 
starting at address is overwritten with data (the length argument has 
no effect on this). 

If length would imply returning storage beyond the virtual machine size, 
only those bytes up to the virtual machine size are returned; and if an 
attempt is made to alter any bytes outside the virtual machine size, they are 
left unaltered. 

Warning: The STORAGE function allows any location in your virtual 
machine to be altered. Do not use this function without due care and 
knowledge. 

Example: 

STORAGE(AA,9) -> 1 IBM VM/SP 1 /* Maybel */ 

STORAGE() -> 1 15E000 1 /* After DEF STOR 1400K */ 
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In addition to the TRACE instruction, described on page 62, there are the 
following debug aids. 

• The interactive debug facility 

• The CMS immediate commands: 

HI - Halt Interpretation 
TS - Trace Start 
TE - Trace End 

• The CMS HELP command. 


Interactive Debugging of Programs 

The debug facility permits interactively controlled execution of a program. 

Changing the TRACE action to one with a prefix ? (for example, TRACE ?A 
or the TRACE built-in function) turns on interactive debug and indicates to 
the user that interactive debug is active. Further TRACE instructions in 
the program are ignored, and the interpreter pauses after nearly all 
instructions that are traced at the console (see below for the exceptions). 
When the interpreter pauses, indicated by a VM READ or unlocking of the 
keyboard, three debug actions are available: 

1. Entering a null line (no blanks even) makes the interpreter continue 
execution until the next pause for debug input. Repeatedly entering a 
null line, therefore, steps from pause point to pause point. For TRACE 
?A, for example, this is equivalent to single-stepping through the 
program. 

2. Entering an equal sign (= ) with no blanks makes the interpreter 
re-execute the clause last traced. For example: if an IF clause is about 
to take the wrong branch, you can change the value of the variable(s) 
on which it depends, and then re-execute it. 

Once the clause has been re-executed, the interpreter pauses again. 

3. Anything else entered is treated as a line of one or more clauses, and 
interpreted immediately (that is, as though DO; line ; END; had been 
inserted in the file). The same rules apply as in the INTERPRET 
instruction (for example, DO-END constructs must be complete). If an 
instruction has a syntax error in it, a standard message is displayed and 
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you are prompted for input again. Similarly all the other SIGNAL 
conditions are disabled while the string is interpreted to prevent 
unintentional transfer of control. 

During execution of the string, no tracing takes place, except that 
non-zero return codes from host commands are displayed. Host 
commands are always executed (that is, are not affected by the prefix ! 
on TRACE instructions), but the variable RC is not set. 

Once the string has been interpreted, the interpreter pauses again for 
further debug input unless a TRACE instruction was entered. In this 
latter case, the interpreter immediately alters the tracing action (if 
necessary) and then continues executing until the next pause point (if 
any). Hence to alter the tracing action (from All to Results for 
example) and then re-execute the instruction, you must use the built-in 
function TRACE (see page 97). For example, CALL TRACE I changes 
the trace action to “I” and allows re-execution of the statement after 
which the pause was made. Interactive debug is turned off when it is in 
effect, if a TRACE instruction uses a prefix, or at any time, when a 
TRACE 0 or TRACE with no options is entered. 

The numeric form of the TRACE instruction may be used to allow 
sections of the program to be executed without pause for debug input. 
TRACE n (that is, positive result) allows execution to continue, skipping 
the next n pauses (when interactive debug is or becomes active). 

TRACE -n (that is, negative result) allows execution to continue 
without pause and with tracing inhibited for n clauses that would 
otherwise be traced. 

The trace action selected by a TRACE instruction is saved and restored 
across subroutine calls. This means that if you are stepping through a 
program (say after using TRACE ?R to trace Results) and then enter a 
subroutine in which you have no interest, you can enter TRACE 0 to turn 
tracing off. No further instructions in the subroutine are traced, but on 
return to the caller, tracing is restored. 

Similarly, if you are interested only in a subroutine, you can put a TRACE 
?R instruction at its start. Having traced the routine, the original status of 
tracing is restored and hence (if tracing was off on entry to the subroutine) 
tracing (and interactive debug) is turned off until the next entry to the 
subroutine. 

Tracing may be switched on (without requiring modification to a program) 
by using the command SET EXECTRAC ON. Tracing may be also turned 
on or off asynchronously, (that is, while a program is running) by using the 
TS and TE immediate commands. See page 119 for the description of these 
facilities. 

Since any instructions may be executed in interactive debug you have 
considerable control over execution. 
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Some examples: 


Say expr 

name=expr 
Trace 0 

Trace ?A 

Trace L 

exit 


/* displays the result of evaluating the */ 

/* expression. */ 

/* alters the value of a variable. */ 

/* (or Trace with no options) turns off */ 

/* interactive debug and all tracing. */ 

/* turns off interactive debug but continue */ 

/* tracing all clauses. */ 

/* makes the interpreter pause at labels */ 

/* only. This is similar to the traditional */ 

/* "breakpoint” function, except that you */ 

/* don't have to know the exact name and */ 

/* spelling of the labels in the program. */ 

/* terminates execution of the program. */ 


Do i=l to 10 /* displays ten elements of the array stem. */ 

say stem.i 

end 


Exceptions: Some clauses cannot safely be re-executed, and therefore the 
interpreter does not pause after them, even if they are traced. These are: 

• Any repetitive DO clause, on the second or subsequent time around the 
loop. 

• All END clauses (not a useful place to pause in any case). 

• All THEN, ELSE, OTHERWISE, or null clauses. 

• All RETURN and EXIT clauses. 


• All SIGNAL and CALL clauses (the interpreter pauses after the target 
label has been traced). 

• Any clause that causes a syntax error. (These may be trapped by 
SIGNAL ON SYNTAX, but cannot be re-executed.) 


Interrupting Execution and Controlling Tracing 

The interpreter may be interrupted during execution in several ways: 

• The HI (Halt Interpretation) immediate command may be used to cause 
all currently executing REXX programs to terminate, as though there 
has been a syntax error. This is especially useful when an editor macro 
gets into a loop, and it is desirable to halt it without destroying the 
whole environment (as HX would do). When a HI interrupt causes a 
REXX program to terminate, the program stack is cleared. A HI 
interrupt may be trapped by using SIGNAL ON HALT, described on 
page 58. 


Part 4: Debug Aids 119 



Debug Aids 


• The TS (Trace Start) immediate command turns on the external tracing 
bit. If the bit is not already on, TS puts the program into normal 
interactive debug and you can then execute REXX instructions etc. as 
normal (for example, to display variables, EXIT, etc.). This too is useful 
when you suspect that a REXX program is looping - TS may be entered, 
and the program can be inspected and stepped before a decision is made 
whether to allow the program to continue or hot. 

• The TE (Trace End) immediate command turns off the external tracing 
bit. If it is not already off, this has the effect of executing a TRACE O 
instruction. This can be useful to stop tracing when not in interactive 
debug (as when tracing was started by issuing SET EXECTRAC ON and 
interactive debug was subsequently terminated by issuing TRACE ?). 

The system (external) trace bit: 

Before each clause is executed, an external trace bit, owned by CMS 
(“EXECTRAC,” see page 164 ) is inspected. The user may turn the bit on 
by the TS immediate command, and turn it off by the TE immediate 
command. The user may also alter the bit by using the SET EXECTRAC 
command (see below). This bit is never altered by CMS itself, except that it 
is cleared on return to CMS command level. 

The interpreter maintains an internal “shadow” of the external bit, which 
therefore allows it to detect when the external bit changes from a 0 to a 1, 
or vice-versa. If the interpreter sees the bit change from 0 to 1, ? 
(interactive debug) is forced on and the tracing action is forced to R if it is 
A, C, E, L, N, or O. The tracing action is left unchanged if it is I, R, or S. 

Similarly, if the shadow bit is seen to change from 1 to 0, all tracing is 
forced off. This means that tracing may be controlled externally to the 
REXX program: interactive debug can be switched on at any time without 
making any modifications to the program. The TE command can be useful 
if a program is tracing clauses without being in interactive debug (that is, 
after SET EXECTRAC ON, TRACE ? was issued). TE may be used to 
switch off the tracing without affecting any other output from the program. 

If the external bit is on upon entry to a REXX program, the SOURCE string 
is traced (see page 47) and interactive debug is switched on as normal -- 
hence with use of the system trace bit, tracing of a program and all 
programs called from it, can be easily controlled. 

The internal “shadow” bit is saved and restored across internal routine 
calls. This means that (as with internally controlled tracing) it is possible 
to turn tracing on or off locally within a subroutine. It also means that if a 
TS interrupt occurs during execution of a subroutine, tracing will also be 
switched on upon RETURN to the caller. 

The CMSFLAG(EXECTRAC) function and the command QUERY 
EXECTRAC may be used to test the setting of the system trace bit. 
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The command SET EXECTRAC ON turns on the trace bit. Using it before 
invoking a REXX program causes the program to be entered with debug 
tracing immediately active. If issued from inside a program, SET 
EXECTRAC ON has the same effect as TRACE ?R (unless TRACE I or S is 
in effect), but is more global in that all programs called are traced, too. 

The command SET EXECTRAC OFF turns the trace bit off. Issuing this 
when the bit is on is equivalent to the instruction TRACE O, except that it 
has a system (global) effect. 

Note: SET EXECTRAC OFF turns off the system trace bit at any time; for 
example, if it has been set by a TS immediate command issued while not in 
a REXX program. 


Help 


The CMS command HELP REXX MENU displays a menu. You can then 
display the description of any REXX instruction, REXX built-in function, or 
RXSYSFN function from this menu. 

Alternatively, any of these may be displayed directly by using: 


HELP REXX T instruction name ~ 
L function name 
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Three instructions (ARG, PARSE, and PULL) allow a selected string to be 
parsed (split up) into variables, under the control of a template. The 
various mechanisms in the template allow a string to be split up into words 
(delimited by blanks), or by explicit matching of patterns, or by selecting 
absolute columns with numeric patterns - for example to extract data from 
particular columns of a record read from a file. 

This section first gives some informal examples of how the parsing template 
can be used, then describes in more detail the mechanisms used. 


Introduction 


Here are some examples that illustrate how parsing works. 


Parsing Words 

The simplest form of a parsing template consists of a list of variable names. 
The data being parsed is split up into words (characters delimited by 
blanks), and each word from the data is assigned to a variable in sequence. 
The final variable is treated differently in that it will be assigned whatever 
is left of the original data and may therefore contain several words, and 
possibly leading and trailing blanks. 

Parse value 'This is a sentence.' with vl v2 v3 
/* is equivalent to: */ 

vl = "This"; v2 = "is"; v3 = "a sentence." 

In this example, vl would get the value This, v2 would get the value is, 
and v3 would get a sentence. 

Leading blanks and trailing blanks are removed from each word in the 
string before it is assigned to a variable, except for the word or group of 
words assigned to the last variable. Variables set in this manner (vl and 
v2 in the example) will never have leading or trailing blanks. But the last 
variable (v3 in the example) could have both leading and trailing blanks, if 
extra blanks were specified before a or after sentence. 


( 
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For example, 

Parse value 'This is a sentence.' with vl v2 v3 
/* is equivalent to: */ 

vl = "This"? v2 = "is"; v3 = " a sentence." 

In this example, vl would get the value This, v2 would get the value is, 
and v3 would get a sentence. 

In addition, if PARSE UPPER (or the ARG or PULL instruction) is used, 
the whole string is translated into uppercase before parsing begins. 

Note that all variables mentioned in a template are always given a new 
value, so if there are fewer words in the data than variables in the template, 
the unused variables will be set to null. 

Parsing Using String Patterns 

A string may be used in a template to split up the data: 

Parse value 'To be, or not to be?' with wl ',' w2 
/* would cause the data to be scanned for the comma, */ 

/* then split at that point, thus: */ 

wl = "To be"; w2 = " or not to be?" 

wl would be set to To be, and w2 is set to or not to be?. A string used 
in this way is called a pattern. Note that the pattern itself (and only the 
pattern) is removed from the data. In fact each section is treated in just the 
same way as the whole string was in the previous example, and so either 
section may be split up into words. 

Parse value 'To be, or not to be?' with wl w2 w3 w4 

/* is equivalent to: */ 

wl = "To be"; w2 = "or"; w3 = "not"; w4 = "to be?" 

w2 and w3 get the values or and not, and w4 would get the remainder: to 
be?. If UPPER was specified on the instruction, all the variables would be 
translated to uppercase. 

If the string in these examples did not contain a comma, the pattern would 
effectively “match” the end of the string, so the variable to the left of the 
pattern would get the entire input string, and the variables to the right 
would be set to null. Note that a null string will never be found, and so 
will always match the end of the string. 

The pattern may be specified as a variable, by putting the variable name in 
parentheses. The following instructions therefore have the same effect as 
the last example: 

comma=', 1 

Parse value 'To be, or not to be?' with wl (comma) w2 w3 w4 
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Parsing Using Numeric Patterns 

The third type of parsing mechanism is the numeric pattern. This works in 
the same way as the string pattern except that it specifies a column 
number. So: 

Parse value 'Flying pigs have wings' with xl 5 x2 
/* would split the data at column 5. Equivalent to */ 

xl = "Flyi"; x2 = "ng pigs have wings" 

would split the data at column 5, so xl would be Flyi and x2 would start 
at column 5 and so be ng pigs have wings. 

More than one pattern is allowed, so for example: 

Parse value 'Flying pigs have wings' with xl 5 x2 10 x3 
/* would split the data at columns 5 and 10. Equivalent to */ 

xl = "Flyi"; x2 = "ng pi"; x3 = "gs have wings" 

would split the data at columns 5 and 10, so x2 would be ng pi and x3 
would be gs have wings. 

The numbers can be relative to the last number used, so 

Parse value 'Flying pigs have wings' with xl 5 x2 +5 x3 

would have exactly the same effect as the last example: here the +5 may be 
thought of as specifying the length of the data to be assigned to x2. 

String patterns and numeric patterns can be mixed (in effect the beginning 
of a string pattern just specifies a variable column number) and some very 
powerful things can be done with templates. The “Definition” section 
(below) describes in more detail how the various mechanisms interact. 


Parsing Arguments 


Finally, it is possible to parse more than one string. For example, an 
internal function may have more than one argument string. To get at each 
string in turn, you just put a comma in the parsing template. For example, 
if the invocation of the function “FRED” was: 

fred('This is the first string',2) 

the instruction 

PARSE ARG first, second 
/* would be equivalent to */ 

first = "THIS IS THE FIRST STRING"; second = "2" 

The variable first contains the string “This is the first string”. The 
variable second contains the string “2”. Between the commas you can put 
a normal template, with patterns, etc., to do more complex parsing on each 
of the argument strings. 
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Definition 


This section describes the rules that govern parsing. 

In its most general form, a template consists of alternating pattern 
specifications and variable names. The pattern specifications and variable 
names are used strictly in sequence from left to right, and are used once 
only. In practice, various simpler forms are used in which either variable 
names or patterns may be omitted: we can therefore have variable names 
without patterns in between, and patterns without intervening variable 
names. 

In general, the value assigned to a variable is that sequence of characters 
in the input string between the point that is matched by the pattern on its 
left and the point that is matched by the pattern on its right. 

If the first item in a template is a variable, there is an implicit pattern on 
the left that matches the start of the string, and similarly if the last item in 
a template is a variable, there is an implicit pattern on the right that 
matches the end of the string. Hence the simplest template consists of a 
single variable name which in this case is assigned the entire input string. 

Setting a variable during parsing is identical to setting a variable in an 
assignment. It is therefore possible to set an entire collection of compound 
variables during parsing. (See pages 13 and 14.) 

The constructs that may appear as patterns fall into two categories: 

• patterns that act by searching for a matching string 

- literal patterns 

— variable patterns 

• numeric patterns that specify a position in the data 

- positional patterns 

— relative patterns 

For the following examples, assume that the following string is being 
parsed (note that all blanks are significant): 

'This is the data which, I think, is scanned.' 


Parsing with Literal Patterns 

Literal patterns cause scanning of the input data string to find a sequence 
that matches the value of the literal. Literals are expressed as a quoted 
string. 
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When the template: 
wl 'f ' w2 *, 9 rest 

is used to parse the example string, the result is: 

wl =“This is the data which” 
w2 = “ I think” 
rest = “ is scanned.” 

Here the string is parsed using a template that asks that each of the 
variables receive a value corresponding to a portion of the original string 
between commas; the commas are given as quoted strings. Note that the 
patterns (in this example, the commas) themselves are removed from the 
data being parsed. 

A different parse would result with the template: 
wl 1 , 1 w2 ', 1 w3 ', 1 rest 

which would result in: 

wl =“This is the data which” 
w2 = “ I think” 
w3 =“ is scanned.” 
rest = “ ” (null) 

This illustrates an important rule. When a match for a pattern cannot be 
found in the input string, it instead “matches” the end of the string. Thus, 
no match was found for the third V in the template, and so w3 was assigned 
the rest of the string. REST was assigned a null value because the pattern 
on its left had already reached the end of the string. 

A null pattern (a string of length 0) may be used to match the end of the 
data explicitly. This is mainly useful with positional patterns (see below). 

Note that all variables that appear in a template are assigned a new value. 

If a variable is followed by another variable, a special action is taken. This 
is similar to there being the pattern ‘ ’ (a single blank) between them, 
except that leading blanks at the current position in the input data are 
skipped over before the search for the next blank takes place. This means 
that the value assigned to the left-hand variable will be the next word in 
the string, and will have neither leading nor trailing blanks. 
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Thus the template: 
wl w2 w3 rest *, 1 

would result in: 

wl =“This” 
w2 = “is” 
w3 =“the” 
rest = “data which” 

Note that the final variable (rest in this example) could have had both 
leading blanks and trailing blanks, since only the blank that delimits the 
previous word is removed from the data. 

Also observe that this example is not the same as specifying explicit blanks 
as patterns, as the template: 

1 rest ' , 1 


which” 

since the third pattern would match the third blank in the data. 

Note: Quotes are not part of the value. They are shown here and in 
following examples only to indicate leading or trailing blanks. 

In general then, when a variable is followed by another variable, parsing of 
the input by tokenization into words is implied. 


wl 1 ’ w2 * ' w3 1 

would in fact result in: 

wl = “This” 

w2 = “is” 

w3 = “ ” (null) 

rest =“the data 


Parsing with Variable Patterns 

It is sometimes desirable to be able to specify a matching pattern by using a 
variable instead of a literal string. This may be achieved by placing the 
name of the variable to be used as the pattern in parentheses. The variable 
may be one that has been set earlier in the parsing process, so for example: 

input =,, L/look for/1 10" 

parse var input verb 2 delim +1 string (delim) rest 

will set: 

verb = “L” 
delim = “/” 
string = “look for” 
rest = “1 10” 


128 VM/SP System Product Interpreter Reference 


Parsing 


Use of the Period as a Placeholder 

The symbol consisting of a single period acts as a placeholder in a template. 
It has exactly the same effect as a variable name, except that no variable is 
set. It is especially useful as a “dummy variable” in a list of variables or to 
collect unwanted information at the end of a string. Thus, when the 
template: 

. . . word4 . 

is used to parse the same example string: 

'This is the data which, I think, is scanned.' 

the result is: 
word4 = "data" 

That is, the fourth word (data) is extracted from the string and placed in 
the variable word4. 

Parsing with Positional Patterns and Relative Patterns 

Positional patterns may be used to cause the parsing to occur on the basis 
of position within the string, rather than on its contents. They take the 
form of signed or unsigned whole numbers, and may cause the matching 
operation to “back up” to an earlier position in the data string. “Backing 
up” can only occur when positional patterns are used. 

Unsigned numbers in a template refer to a particular character column in 
the input. For example, the template 

si 10 s2 20 s3 
results in 

si =“This is ” 
s2 =“the data w” 

s3 =“hich, I think, is scanned.” 

Here si is assigned characters from input through the ninth character, and 
s2 receives input characters 10 through 19. The final variable, s3, is 
assigned the remainder of the input. 

Signed numbers may be used as patterns to indicate movement relative to 
the character position at which the previous pattern match occurred. 

If a signed number is specified, the position used for the next match is 
calculated by adding or subtracting the number given to the last matched 
position. The last matched position is the position of the first character 
of the last match, whether specified numerically or by a string. For 
example, the instructions: 
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a = 1 123456789 * 

parse var a 3 wl +3 w2 3 w3 

result in: 

wl = “345” 
w2 = “6789” 
w3 = “3456789” 

The +3 in this case is equivalent to the absolute number 6 in the same 
position, and indeed may be considered as specifying the length of the data 
to be assigned to the variable wl. 

This example also illustrates the effects of a pattern that implies movement 
to a character position to the left of, or to the point where matching has 
already occurred. Movement is from column 6, the starting position for w2, 
to column 3, the starting position for w3. The variable on the left is 
assigned characters through the end of the input, and the variable on the 
right is, as usual, assigned characters starting at the position dictated by 
the pattern. 

A useful effect of this is that multiple assignments can be made: 
parse var x 1 wl 1 w2 1 w3 

results in assigning the (entire) value of x to wl, w2, and w3. (The first “1” 
here could be omitted as it is effectively the same as the implicit starting 
pattern described at the beginning of this section.) 

The following PARSE instruction assigns the same values to wl, w2, and w3 
as above: 

a = 1 123456789 1 

parse var a 3 wl +3 w2 -3 w3 

3 specifies the starting position for wl, column 3. +3 tells you to move 3 
positions to the right of the starting position of wl. This is the starting 
position of w2, column 6. -3 tells you to move 3 positions to the left of the 
starting position of w2. This is the starting position of w3, column 3. 

If a positional pattern specifies a column that is greater than the length of 
the data, it is equivalent to specifying the end of the data (that is, no 
padding takes place). Similarly, if a pattern specifies a column to the left of 
the first column of the data, this is not an error but instead is taken to 
specify the first column of the data. 

Any pattern match sets the “last position” in a string to which a relative 
positional pattern can refer. The “last position” set by a literal pattern is 
the position at which the match occurred; that is, the position in the data of 
the first character in the pattern. Thus the template: 

1 , 1 -1 x +1 
will: 
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1. Find the first comma in the input (or the end of the string if there is no 
comma). 

2. Back up one position. 

3. Assign one character (the character immediately preceding the comma 
or end of string) to the variable x. 

A possible application of this is looking for abbreviations in a string. Thus 
the instruction: 

/* Ensure options have leading blank and are uppercase */ 
parse upper value 1 'opts with ' PR' +1 prword ' 1 

will set the variable prword to the first word in opts that starts with PR or 
will set it to null if no such word exists. Note that +0 is a valid positional 
pattern. 

When a literal pattern is followed by a signed( 4- /-) positional pattern the 
literal string WILL NOT BE REMOVED from the data being parsed. 

Instead it will be parsed into the first variable following the literal pattern. 
Thus the following two cases: 

a='This is the data which, I think, is scanned.' 

CASE 1: parse var a 'which' +5 y 

CASE 2: parse var a 'which'x +5 y 

would result in: 

CASE 1: y =“, I think is scanned” 

CASE 2: x = “which” 

y = “, I think is scanned.” 

Note: If a number in a template is preceded by a “ + ” or a this is taken 
to be a signed positional pattern. There may be blanks between the sign 
and the number, since initial scanning removes blanks adjacent to special 
characters. 


Parsing Multiple Strings 

A parsing template can parse multiple strings. This is effected by using 
the special character comma (,) in the template. Each comma is an 
instruction to the parser to move on to the next string. For each string a 
normal template (with patterns, etc.) may be specified. The only time 
multiple strings are available is in the ARG (or PARSE ARG) instruction. 
When an internal function or subroutine is invoked it may have several 
argument strings, and a comma is used to access each in turn. Thus the 
template: 

wordl stringl, string2, num 


Part 5: Parsing for PARSE, ARG and PULL 131 




Parsing 


would put the first word of the first argument string into wordl, the rest of 
that string into stringl, and the next two strings into string2 and num. 
If insufficient strings were specified in the invocation, unused variables are 
set to null, as usual. 
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REXX defines the usual arithmetic operations (addition, subtraction, 
multiplication, and division) in as “natural” a way as possible. What this 
really means is the rules followed are those that are conventionally taught 
in schools and colleges. 

During the design of these facilities, however, it was found that 
unfortunately the rules used vary considerably (indeed much more than 
generally appreciated) from person to person and from application to 
application and in ways that are not always predictable. The arithmetic 
described here is therefore a compromise that (although not the simplest) 
should provide acceptable results in most applications. 


Introduction 


Numbers (that is, character strings used as input to REXX arithmetic 
operations) can be expressed very flexibly. Leading and trailing blanks are 
permitted, and exponential notation may be used. Some valid numbers are: 


12 /* an integer */ 

-76 /* signed integer */ 

12.76 /* decimal places */ 

* + 0.003 ' /* blanks around the sign etc */ 

17. /* same as "17" */ 

.5 /* same as "0.5" */ 

4E9 /* exponential notation */ 

0.73e-7 /* exponential notation */ 


(Exponential notation means that the number includes a power of ten 
following an E that indicates how the decimal point should be shifted. 
Thus 4E9 above is just a short way of writing 4000000000, and 0.73e-7 is 
short for 0.000000073.) 

The Arithmetic operators include addition (+), subtraction (-), 
multiplication (*), exponentiation (**), and division (/). In addition, there 
are two further division operators: integer divide (%) that divides and 
returns the integer part, and remainder (//) that divides and returns the 
remainder. 

The result of an arithmetic operation is formatted as a character string 
according to definite rules. The most important of these rules are as 
follows (see the Definition section for full details): 

• A number will be displayed with up to some maximum number of 
significant digits (the default is 9, but this may be altered with the 
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NUMERIC DIGITS instruction to give whatever accuracy you need). 
Thus if a result requires more than 9 digits, it would normally be 
rounded to 9 digits. For example, the division of 2 by 3 would result in 
0.666666667 (it would require an infinite number of digits for perfect 
accuracy). 

• Except for division and exponentiation, trailing zeros are preserved 
(this is in contrast to most popular calculators, which remove all 
trailing zeros). So, for example: 

2.40 +1 -> 3.40 

2.40 - 2 -> 0.40 

2.5 * 2 -> 5.0 

This behavior is desirable for most calculations (especially financial 
calculations). 

If necessary, trailing zeros may be easily removed with the STRIP 
function (see page 94), or by division by 1. 

• A zero result is always expressed as the single digit 0. 

• Exponential form is used for a result depending on the setting of 
NUMERIC DIGITS (the default is 9). If the number of places needed 
before the decimal point exceeds the NUMERIC DIGITS setting, or the 
number of places after the point exceeds twice the NUMERIC DIGITS 
setting, the number will be expressed in exponential notation: 

le6 * le6 -> 1E+12 

/* not 1000000000000 */ 

1 / 3E10 -> 3.33333333E-11 

/* not 0.0000000000333333333 */ 


Definition 

A precise definition of the arithmetic facilities of the REXX language is 
given here. 

Numbers 


A number in REXX is a character string that includes one or 
more decimal digits, with an optional decimal point. The decimal 
point may be embedded in the number, or may be prefixed or 
suffixed to it. The group of digits (and optional decimal point) 
constructed this way may have leading or trailing blanks and an 
optional sign (+ or -) that must come before any digits or 
decimal point. 
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In other words (in Backus-Naur like form, where :: = stands for 
“is defined as,” | stands for “or,” and blanks are not significant 
except where represented by the word “blank”): 


sign 

digit 

digits 

numeric 


number 


+ I " 

0|1|2|3|4|5|6|7|8|9 
digit[digit]... 


{ digits } 

{ digits.digits } 
C .digits } 

{ digits. } 


[blank]... [sign [blank]...] 

numeric [blank]... 


Note that a single period alone is not a valid number. 


Precision 


The maximum number of significant digits that can result from 
an operation is controlled by the instruction: 

NUMERIC DIGITS [expression] 

expression is evaluated and must result in a positive whole 
number. This defines the precision (number of significant digits) 
to which calculations are carried out. Results are rounded to 
that precision. 

If expression is not specified in this instruction, or if no 
NUMERIC DIGITS instruction has been executed since the start 
of a program, the default precision is used. The REXX standard 
for the default precision is 9, and this is what is implemented by 
the interpreter. 

Arithmetic operators 

The four basic operators + , - , * , and / (add, subtract, multiply, 
and divide) produce results that are rounded if necessary to the 
precision specified by the NUMERIC DIGITS instruction. 

Every operation is carried out in such a way that no errors will 
be introduced except during the final rounding of the result to 
the specified significance. (That is, input data is first truncated 
to the appropriate significance (NUMERIC DIGITS +1) before 
being used in the computation, and then divisions and 
multiplications are carried out to double that precision, as 
needed.) 

Rounding is done in the “traditional” manner, in that the digit to 
the right of the least significant digit in the result (the “guard 
digit”) is inspected and values of 5 through 9 are rounded up, and 
values of 0 through 4 are rounded down. Even/odd rounding 
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would require the ability to calculate to arbitrary precision at all 
times and is therefore not the mechanism defined for REXX. 


A conventional zero is supplied in front of the decimal point, 
otherwise there would be no digit preceding it. Significant 
trailing zeros are retained for addition, subtraction, and 
multiplication, according to the rules given below, except that a 
result of zero is always expressed as the single digit 0. For 
division, trailing zeros are removed after rounding. 


The FORMAT built-in function is supplied (see page 85) to allow 
a number to be represented in a particular format if the standard 
result provided does not meet your requirements. 


The precise rules for the operations are described below, but the 
following examples illustrate the main implications of the rules: 


/* With: 

Numeric 

digits 5 

12+7.00 

-> 

19.00 

1.3-1.07 

-> 

0.23 

1.3-2.07 

-> 

-0.77 

1.20*3 

-> 

3.60 

7*3 

-> 

21 

0.9*0.8 

-> 

0.72 

1/3 

-> 

0.33333 

2/3 

-> 

0.66667 

5/2 

-> 

2.5 

1/10 

-> 

0.1 

12/12 

-> 

1 

8.0/2 

-> 

4 


The exponentiation operator (**), integer divide operator (%), 
and remainder operator (//) are also defined: 

The ** (exponentiation) operator raises a number to a whole 
power, which may be positive or negative. If negative, the 
absolute value of the power is used, and then the result is 
inverted (divided into 1). For calculating the result, the number 
is effectively multiplied by itself for the number of times 
expressed by the power, and finally trailing zeros are removed (as 
though the result were divided by one). In practice (see note 
below for rationale), the result is calculated by the process of 
left-to-right binary reduction. For x**n: n is converted to 
binary, and a temporary accumulator is set to 1. If n = 0 the 
calculation is complete. Otherwise each bit (starting at the first 
non-zero bit) is inspected from left to right. If the current bit is 
1, the accumulator is multiplied by x. If all bits have now been 
inspected the calculation is complete, otherwise the accumulator 
is squared and the next bit is inspected for multiplication. When 
the calculation is complete, the temporary result is ready for 
division by or into 1 to provide the final answer. The 
multiplications and division are done under the normal REXX 
arithmetic combination rules, detailed below. (Note that a 
number is rounded to the current setting of NUMERIC DIGITS 


136 VM/SP System Product Interpreter Reference 





Numerics and Arithmetic 


before the first multiplication, and that intermediate results are 
rounded after each subsequent multiplication.) 

The % (integer divide) operator divides two numbers and 
returns the integer part of the result, which will not be rounded 
unless the integer has more digits than the current DIGITS 
setting. The result returned is defined to be that which would 
result from repeatedly subtracting the divisor from the dividend 
while the dividend is larger than the divisor. During this 
subtraction, the absolute values of both the dividend and the 
divisor are used: the sign of the final result is the same as that 
which would result if normal division were used. Note that this 
operator may not give the same result as truncating normal 
division (which could be affected by rounding). 


The // (remainder) operator will return the remainder from 
integer division, and is defined such that: 

a//b == a-(a%b)*b 


Thus: 


/* Again 

with 

2**3 

-> 

2**-3 

-> 

1.7**8 

-> 

2%3 

-> 

2.1//3 

-> 

10%3 

-> 

10//3 

-> 

-10//3 

-> 

10.2//1 

-> 

10//0.3 

-> 


Numeric digits 
8 

0.125 

69.758 

0 

2.1 

3 

1 

-1 

0.2 

0.1 


5 


V 


Note: A particular algorithm for calculating exponentiation is 
used, since it is efficient (though not optimal) and considerably 
reduces the number of actual multiplications performed. It 
therefore gives better performance and can give higher accuracy 
than the simpler definition of repeated multiplication. Since 
results may differ from those of repeated multiplication, the 
algorithm is defined here. 

Arithmetic combination rules 

The rules for combination of two numbers by the four basic 
operators are as follows. All numbers have insignificant leading 
zeros removed before being used in computation. 

Addition and Subtraction 

The numbers are extended on the right and left as necessary 
and then added or subtracted as appropriate. 
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Example: 


xxx.xxx + yy.yyyyy 

becomes: xxx.xxxOO 

+ Oyy.yyyyy 

zzz.zzzzz 

The result is then rounded to the current setting of 
NUMERIC DIGITS if necessary, and any insignificant 
leading zeros are removed. 

Multiplication 

The numbers are multiplied together (“long multiplication”) 
resulting in a number that may be as long as the sum of the 
lengths of the two operands. 

Example: 


xxx.xxx * yy.yyyyy 
becomes: zzzzz.zzzzzzzz 

The result is then rounded to the current setting of 
NUMERIC DIGITS. 

Division 

For the division: 
yyy / xxxxx 

the following steps are taken: First the number yyy is 
extended to be at least as long as the number xxxxx (with 
note being taken of the change in the power of ten that this 
implies). Thus in this example, yyy becomes yyyOO. 
Traditional long division then takes place, which might be 
written: 


zzzz 


xxxxx ) yyyOO 

The length of the result (zzzz) is such that the rightmost z 
will be at least as far right as the rightmost digit of the 
(extended) y number in the example. During the division, 
the y number will be extended further as necessary, and the 
z number may increase up to NUMERIC DIGITS +1 digits at 
which point the division stops and the result is rounded. 
Following completion of the division (and rounding if 
necessary), insignificant trailing zeros are removed. 


Note: In the above examples, the position of the decimal point is 
arbitrary. In fact the operations may be carried out as integer 
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operations with the exponent being calculated and applied after. 
Therefore none of the operations are in any way dependent on 
the position of the decimal point and hence results are 
completely independent of the number of decimal places. 

Comparison Operators 


The comparison operators are listed on page 8. Any of these may 
be used for comparing numeric strings. However, = = and 
~i = = , should not be used to compare numeric values because 
leading/trailing blanks and leading zeroes are significant with 
these two operators. 

A comparison of numeric values is effected by subtracting the 
two numbers (calculating the difference) and then comparing the 
result with 0. For example, the operation: 

A ? B 

where ? is any numeric comparison operator, is identical to: 

(A - B) ? 'O’ 


It is therefore the difference between two numbers, when 
subtracted under REXX subtraction rules, that determines their 
equality. 

Comparison of two numbers is affected by a quantity called 
“fuzz,” which is set by the instruction: 

NUMERIC FUZZ [expression] 


Here expression must result in a whole number that is zero or 
positive. This FUZZ number controls the amount by which two 
numbers may differ before being considered equal for the purpose 
of comparison. The default is 0. 

The effect of FUZZ is to temporarily reduce the value of DIGITS 
by the FUZZ value for each comparison operation. That is, the 
numbers are subtracted under a precision of DIGITS-FUZZ digits 
during the comparison. Clearly FUZZ must be less than DIGITS. 


Thus if DIGITS = 9, and FUZZ = 1, the comparison will be 
carried out to 8 significant digits, just as though NUMERIC 
DIGITS 8 had been put in effect for the duration of the operation. 
Example: 


Numeric digits 5 
Numeric fuzz 0 
say 4.9999 = 5 
say 4.9999 < 5 
Numeric fuzz 1 
say 4.9999 = 5 
say 4.9999 < 5 


/* would display 0 
/* would display 1 

/* would display 1 
/* would display 0 


V 

V 

V 

V 
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Exponential notation 

The description above describes “pure” numbers, in the sense 
that the character strings that describe numbers could be very 
long. For example: 

10000000000 * 10000000000 

could give 100000000000000000000 

and 

.00000000001 * .00000000001 

could give 0.000000000000000000001 

For both large and small numbers some form of exponential 
notation is useful, both to make numbers more readable, and to 
reduce execution time storage requirements. In addition, 
exponential notation is used whenever the “simple” form would 
give misleading information. For example 

numeric digits 5 
say 54321*54321 

would display 2950800000 if long form were to be used. This is 
clearly misleading, and so the result is expressed as 2.9508E + 9 
instead. 

The definition of “numbers” (see above) is therefore extended as 
(note that blanks are shown below only for readability): 


numeric 


digits 

digits.digits [E [sign] digits 
.digits 
digits. 


the integer following the E represents a power of ten that is to be 
applied to the number; and the E may be in uppercase or 
lowercase. 

Here are some examples: 

12E11 = 1200000000000 

12E-5 = 0.00012 

-12e4 = -120000 

The above numbers are valid for input data at all times. The 
results of calculations will be returned in either conventional or 
exponential form depending on the setting of DIGITS. If the 
number of places needed before the decimal point exceeds 
DIGITS, or the number of places after the point exceeds twice 
DIGITS, exponential form will be used. The exponential form 
generated by REXX always has a sign following the E in order to 
improve readability. An exponential part of E + 0 will never be 
generated. 
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Numbers may be explicitly converted to exponential form, or 
forced to be displayed in “long” form, by using the FORMAT 
built-in function, described on page 85. 

The user may control whether Scientific or Engineering notation 
is to be used by using the instruction: 


NUMERIC FORM 


SCIENTIFIC 

ENGINEERING 


The default setting of FORM is SCIENTIFIC. 

Scientific notation adjusts the power of ten so there is a single 
non-zero digit to the left of the decimal point. Engineering 
notation causes powers of ten to always be expressed as a 
multiple of 3: the integer part may therefore range from 1 
through 999. 

/* after the instruction */ 

Numeric form scientific 

123.45 * lell -> 1.2345E+13 

/* after the instruction */ 

Numeric form engineering 

123.45 * lell -> 12.345E+12 

Numeric Information 

The current settings of the NUMERIC options may be found by 
using the NUMERIC option of the PARSE instruction: 

PARSE NUMERIC [template] 

This will parse the current settings of the numeric parameters, in 
the order: DIGITS, FUZZ, FORM. If the defaults were in effect, 
for example, this would cause the following string to be parsed: 

* 9 0 SCIENTIFIC’ 

Use of Numbers by REXX 

Whenever a character string is used as a number (for example as 
an argument to a built-in function, or the expressions on a DO 
clause), rounding may occur according to the setting of 
NUMERIC DIGITS. 


Errors 


Various types of errors may occur in computation: 
• Overflow/Underflow 
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This error will occur if the exponential part of a result 
becomes greater than 999999999 or becomes less than 
-999999999. The exponential part of a result exceeds the 
range that may be handled by the interpreter. Since this 
allows for (very) large exponents, overflow or underflow is 
treated as a terminating “syntax” error. 

• Storage exception 

Storage is needed for calculations and intermediate results, 
and on occasion an arithmetic operation may fail due to lack 
of storage. This is considered a terminating error as usual, 
rather than an arithmetical error. 
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Keywords may be used as ordinary symbols in many situations where there 
is no ambiguity. The precise rules are given here. 

There are three special variables: RC, RESULT and SIGL. 


Reserved Keywords 

The free syntax of REXX implies that some symbols are reserved for use by 
the interpreter in certain contexts. 

Within particular instructions, some symbols may be reserved to separate 
the parts of the instruction: for example, the WHILE in a DO instruction, 
or the THEN (which acts as a clause terminator in this case) following an 
IF or WHEN clause. 

Only non-compound symbols that are the first in a clause and that are not 
followed by an = or : are checked to see if they are instruction keywords: 
the symbols may be freely used elsewhere in clauses without being taken to 
be keywords. 

Therefore, keywords can only have an adverse affect if the user wants to 
execute a host command or subcommand with the same name as a REXX 
keyword (QUEUE, for example). 

This is potentially a problem for any programmer whose REXX programs 
might be used for some time and in circumstances outside his or her 
control, and who wishes to make the programs absolutely “watertight.” 

In this case, a REXX program may be written with (at least) the first words 
in command lines enclosed in quotes. 

Example: 

* ERASE 1 Fn Ft Fm 

This also has an advantage in that it is more efficient; and with this style, 
the SIGNAL ON NOVALUE condition may be used to check the integrity 
of an EXEC. 

An alternative strategy is to precede such command strings with two 
adjacent quotes, which will have the effect of concatenating the null string 
on to the front. 


Part 7: Reserved Keywords and Special Variables 143 


Keywords and Variables 


Example: 

1 ‘Erase Fn Ft Fm 

A third option is to enclose the entire expression (or the first symbol) in 
parentheses. 

Example: 

(Erase Fn Ft Fm) 

More important, the choice of strategy (if it is to be done at all) is a 
personal one by the programmer. It is not imposed by the REXX language. 


Special Variables 

There are three special variables that may be set automatically by the 
interpreter: 

RC is set to the return code from any executed host command (or 

subcommand). Following the SIGNAL events, SYNTAX and 
ERROR, RC is set to the code appropriate to the event: the 
syntax error number (see appendix on error messages, page 177) 
or the command return code. RC is unchanged following a 
NOVALUE or HALT event. 

Note: Host commands executed manually from debug mode do 
not cause the value of RC to change. 

RESULT is set by a RETURN instruction in a subroutine that has been 
CALLed if the RETURN instruction specifies an expression. If 
the RETURN instruction has no expression on it, RESULT is 
dropped (becomes uninitialized.) 

SIGL contains the line number of the clause currently executing when 
the last transfer of control to a label took place. (This could be 
caused by a SIGNAL, a CALL, an internal function invocation, 
or a trapped error condition.) 

None of these variables has an initial value. They may be altered by the 
user, just like any other variable, and they may be accessed, via the “Direct 
Interface to Current Variables” on page 159. The PROCEDURE and DROP 
instructions also affect these variables in the usual way. 

Certain other information is always available to a REXX program. This 
includes the name by which the program was invoked and the source of the 
program (which is available using the PARSE SOURCE instruction, see 
page 47). The latter consists of the string CMS followed by the call type 
and then the filename, filetype, and filemode of the file being executed. 
These are followed by the name by which the program was invoked and the 
initial (default) command environment. 
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In addition, PARSE VERSION (see page 48) makes available the version 
and date of the interpreter code that is running. The built-in functions 
TRACE and ADDRESS return the current trace setting and environment 
name respectively. 
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There are a number of CMS commands that can be especially useful to 

REXX programmers. Some can access and change REXX variables. 

EXECDROP Purges storage-resident EXECs. 

EXECIO Reads and writes CMS files. Issues CP commands, placing 

the output that would normally appear on the screen in the 
program stack. Reads from the virtual reader. Writes to 
the virtual printer and virtual punch. 

EXECLOAD Loads an EXEC into storage. 

EXECMAP Lists storage-resident EXECs. 

EXECOS Cleans up after OS,VSAM and Vector programs, and should 

be used if more than one OS or VSAM program is called 
between returns to CMS command level. 

EXECSTAT Provides the status of a specified EXEC. 

EXECUPDT An extension to the UPDATE command, EXECUPDT 
modifies a REXX program file with one or more update 
files. The input files must have fixed length, 80-column 
records. The result is an executable, V-format program file. 

GLOBALV Saves EXEC data (variables) from one invocation to the 
next. 

IDENTIFY Displays or stacks userid, nodeid, rscsid, date, time, time 
zone, and day of the week. 

LISTFILE Lists information about CMS disk files. 

PARSECMD Parses and translates an exec's arguments. 

QUERY See SET below. (See also the CMSFLAG function.) 

SET ABBREV, IMPEX and IMPCP modify the search order; 

CMSTYPE controls output to the screen (including output 
generated by the SAY instruction); EXECTRAC controls 
tracing. 
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XEDIT When used as an Editor, additional subcommands (macros) 

may be written in REXX. XEDIT may also be used to write 
and read menus (full screen displays). In both applications, 
XEDIT variables may be assigned to REXX variables using 
the EXTRACT subcommand of XEDIT. 

XMITMSG Accesses messages from a repository file. These messages 
can then be displayed. 

For more details on these CMS commands, refer to the VM/SP CMS 

Command Reference. 
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This chapter is addressed mainly to assembler language programmers and 1 

system programmers. It describes: I 

1. Calls to and from the interpreter. A general description of calls to and 
from the REXX programs (from the CMS command line, from another 

EXEC, and so on) with an indication of the type of parameter list used ! 

in each case. j 

2. DMSEXI—the CMS interface module that receives calls to EXEC 
programs and passes them to the appropriate processor or interpreter. 

3. Parameter lists. Details, at assembler language level, of the parameter 
lists used for calls to and from the interpreter. 

4. Function Packages. How to write a function or subroutine that can be 
called by the interpreter and how to put it into a Function Package. 

5. The EXECCOMM subcommand, which allows other programs to read 
and alter REXX variables and extract other information. 

6. How the interpreter sets and tests the flags in the EXECFLAG control 
byte so as to obey the CMS immediate commands HI (Halt Interpreter), 

TS (Trace Start), and TE (Trace End). 


Calls To and From the Interpreter 

When called, the interpreter can process either the Tokenized Plist 
(Parameter List) or an Extended Plist. When calling, the interpreter 
generates both Plists. A special parameter list (subsequently referred to in 
this manual as the six-word Extended Plist) is used by the interpreter for 
function calls and subroutine calls. The contents of the General Register 1 
high order byte (Byte 0) define the format of the Plist passed by the caller. 

Note: The general formats for CMS Plists (parameter lists) are described 
under “CMS SVC Handling” in the VM/SP CMS for System Programming . 
The Extended Plist and the six-word Extended Plist are described below. 


Part 9: System Interfaces 149 


System Interfaces 


Calls Originating from the CMS Command Line 

To invoke a REXX language EXEC, the user may enter on the command 
line: 

• Just the name of the EXEC (execname) and the argument string. In 
this case, if IMPEX is ON (the default) and if the file execname EXEC 
exists, CMS issues the command EXEC, using the original command 
line as the argument string. If IMPEX is OFF, the EXEC cannot be 
invoked in this way, and the word EXEC must be given explicitly. 

Note: If ABBREV is ON (the default) DMSINT will search the synonym 
tables. 

• The command EXEC followed by the name of the REXX language EXEC 
(and the argument string, if any). 

Note: In this case synonyms are not recognized. 

In both cases CMS invokes SVC 202 with Register 0 pointing to the 
Extended Plist, and Register 1 pointing to a Tokenized Plist. Register 1 
byte 0 contains X‘0B\ which signifies that this is a CMS environment call, 
that the full CMS search order was used, and that an Extended Plist is 
available. Control is passed to the interpreter via the EXEC command 
handler (DMSEXI, see below). 


Calls Originating from the XEOIT Command Line 

To invoke a REXX macro that is stored in a file with a filetype of XEDIT, 
the user may enter on the XEDIT command line: 

• Just the name of the macro and the argument string (if any). In this 
case, XEDIT executes the subcommand MACRO, using the original 
command line as the argument string. Note that if the macro has the 
same name as an XEDIT built-in command, it will not be invoked unless 
MACRO is set ON (which is not the default). 

• The command MACRO followed by the name of the REXX macro (and 
the argument string, if any). This will always invoke the specified 
macro, if it exists. 

In both cases XEDIT checks to see if the macro is already loaded into 
storage. If not, it loads the macro if it exists, constructing an Extended 
Plist, a File Block, and a Program Descriptor List. Word 4 of the Extended 
Plist points to the File Block. Register 1 byte 0 contains X‘01’ (which 
signifies that the Extended Plist is available). Control is passed to the 
interpreter via the EXEC command handler (DMSEXI, see below). 

If the user enters the name of the macro (macroname ...) on the XEDIT 
command line and the file macroname XEDIT is not found and IMPCMSCP 
is set ON, XEDIT assumes that an EXEC or a CMS command is being 
invoked, and will try the normal full CMS search order for the command, as 
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though the command had been entered from the CMS command line. In 
this case, Register 1 byte 0 will be X‘0B\ as usual. 

Calls Originating from CMS EXECs 

Calls from CMS EXECs must be explicit invocations of EXEC. Only the 
Tokenized Plist is available. If the called EXEC is written in REXX, 
DMSEXI constructs an argument string from the tokenized Plist. The high 
order byte of R1 is dependent upon the setting of the &CONTROL statement 
- X‘0D* if MSG was specified (default), and X'OE* if NOMSG was specified. 


Calls Originating from EXEC 2 Programs 

Calls originating from EXEC 2 programs must again be explicit invocations 
of EXEC. However, EXEC 2 provides both the Tokenized Plist and the 
Extended Plist. The high order byte of Register 1 is X‘01\ which signifies 
that the Extended Plist is available. 


Calls Originating from a Clause That Is an Expression 

For a REXX clause that is an expression, the resulting string is issued as a 
command to whichever environment is currently selected (See pages 16-22). 
The Plist format used is dependent upon the environment selected (by 
default or by the ADDRESS instruction). 

If the environment for the command is CMS, the call is the same as from 
the CMS command line (same search order, same Plist structure, and the 
high order byte of Register 1 is set to X'OB’). 

If the environment is COMMAND (or null), the command is issued directly: 
the high order byte of Register 1 is set to X‘01’ and CMS is called using 
SVC 202. (Note to EXEC 2 users: this is the way in which EXEC 2 issues 
commands.) 

Note that (whether the environment is CMS or COMMAND) no cleanup is 
performed by DMSINT after the command has been executed, interrupts are 
not cancelled, and the LASTCMD field in NUCON is not updated. 

When the environment is XEDIT (for calls from XEDIT macros, for 
example), the subcommands are passed to XEDIT using the SUBCOM Plist. 
The high order byte of Register 1 is X‘02’ indicating that the call is to a 
CMS subcommand environment. Register 1 points to a Tokenized Plist that 
gives the name of the subcommand entry point that is to receive control 
(XEDIT in this case), and Register 0 points to the Extended Plist. 

All other environment names are treated in the same way as XEDIT, that 
is, the SUBCOM mechanism is used (unless the name is a valid PSW - see 
page 158). 
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Calls Originating from a CALL Instruction or a Function Cali 

A different interface is used when the interpreter calls an external 
subroutine or function. The called routine may be a MODULE, a Nucleus 
Extension, or a REXX program; all use the same Plist, but a FILEBLOK is 
provided by the interpreter only when the routine is called via the EXEC 
interface. The search order for external routines is described on page 71. 

In all cases, Register 1 byte 0 contains X‘05’, indicating that the six-word 
Extended Plist is used. Word 5 of this Plist points to the argument list (see 
page 155). Word 6 points to a fullword location in USER storage, which is 
zero on entry and will be used to store the address of an EVALBLOK if a 
result is returned. A routine that does not return a result must leave this 
location unchanged. 

A routine called as a function must return a result, but a routine called as 
a subroutine need not. The caller sets Register 0 Bit 0 to: 

0 if the routine is called as a function 
1 if the routine is called as a subroutine 

(If the called routine is an EXEC written in REXX this information can be 
obtained using the PARSE SOURCE instruction, described on page 47.) 

If the REXX program is being called as a function, it must end with a 
RETURN or EXIT instruction with an expression, and the resulting string 
is returned in the form of an EVALBLOK. 

Note: DMSEXI always passes control to the interpreter when a high order 
byte ofX‘05’ is found in Register 1. 


Calls Originating from a MODULE 

REXX may be called from a user MODULE using any of the standard forms 
of Plist: 

• Only the Tokenized Plist: Register 1 byte 0 contains ‘OO’X. Register 0 is 
not used. 

• The Extended Plist: Register 1 byte 0 contains ‘Ol’X. Register 1 must 
point to a doubleword-aligned 16-byte field, containing 

CL8 1 EXEC 1 
CL8 * execname' 

The rest of the Tokenized Plist will not be inspected. Register 0 must 
point to an Extended Plist. The FILEBLOK may be provided if desired 
(see page 155). 

• The six-word Extended Plist: Register 1 byte 0 contains ‘05’X. Other 
conditions are the same as for the Extended Plist. This form should be 
used if more than one argument string is to be passed to the EXEC, or 
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the EXEC is being called as a function. (Note that if the EXEC returns 
data in an EVALBLOK, it is the responsibility of the caller to free that 
storage.) 


DMSEXI 


All calls to the CMS command EXEC are first processed by DMSEXI, which 
builds any necessary argument strings and also selects the language 
interpreter which is to process the program. 

This selection is done by reading up to 255 bytes of the first line of the 
program file (or Fileblock defined data) and scanning it until the first 
non-blank character is met. 

1. If the first non-blank characters are /* (that is, the start of a REXX 
comment) or if Register 1 Byte 0 is X‘05\ the program is assumed to be 
written in the REXX language. 

2. If the first non-blank characters are &TRACE, (or if Register 1 Byte 0 is 
X‘0r or X‘0B’ and a FILEBLOK exists, indicating that the call cannot 
be processed by CMS EXEC), the program is assumed to be written in 
the EXEC 2 language. 

3. Otherwise the program is assumed to be written in the CMS EXEC 
language. 

DMSEXI calls the appropriate interpreter. 


The Extended Parameter list 

The interpreter may be called with an Extended Plist (in addition to the 

8-byte Tokenized Plist) that allows the following possibilities: 

• One or more arbitrary parameter strings (mixed case and untokenized) 
may be passed to the interpreter, and one string may be returned from it 
when execution ends. 

• A file other than that defined in the Tokenized Plist may be used. (The 
filetype, for example, need not be EXEC). 

• A default target for commands (other than CMS) can be specified. A 
filetype other than EXEC or blanks will cause commands to go to the 
environment with the name that matches the filetype. 

• A program that exists in storage may be executed (instead of first being 
read from a file). This in-storage execution option may be used for 
improved performance when a REXX program is being executed 
repeatedly. 
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• A default target for commands may be specified that overrides the 
default derived from the filetype. 


Using the Extended Parameter List 

To use the Extended Plist, both Register 1 and Register 0 are used. 

Register 1 points to the Tokenized Plist. The first token of this Plist must 
be CL8‘EXEC’, and the second token must contain the name of the EXEC or 
macro to be processed unless a FILEBLOK that specifies the name is 
provided. 

Byte 0 of Register 1 may have the following values: 

X‘0r or X‘0B’ Extended Plist available. The argument string defined by 
words 2 and 3 (BEGARGS and ENDARGS) of the Extended 
Plist is used to find the called name of the program and the 
argument string passed to the interpreter. The first two 
tokens of the Tokenized Plist are used. 


X‘05’ an interpreter call (for example, originating from a CALL 

instruction or a function call to a REXX external routine). 
The six-word Extended Plist is available. The argument list 
pointed to by Word 5 of the Plist is used for the strings 
accessed by the ARG instruction and the ARG function. 
Only the first token of the Tokenized Plist is used. If the 
argument list is specified, only the first word of the 
BEGARGS/ENDARGS string is used (for the called name of 
the program). 

Any other value (for example, X‘00’) Only the Tokenized Plist is available. 


Register 0 points to the Extended Plist. The Extended Plist has the form: 
EPLIST DS OF PLIST with pointers: 



DC 

A(COMVERB) 

-> 


DC 

A(BEGARGS) 

"> 

* 

DC 

A(ENDARGS) 

-> 

* 

DC 

A(FBLOK) 

-> 


* 


CL5 1 EXEC 1 
start of Argstring 
character after end of 
the Argstring 

File Block, described below, 
(if there is no File Block, 
this pointer must be 0) 


The six-word Extended Plist (which only exists if Register 1 byte 0 is X‘05’) 
is the same four pointers followed by: 


DC AL4(ARGLIST) -> 

* 

* 

* 

* 

DC A(SYSFUNRT) -> 

* 

* 

* 

* 

* 


Argument list. 

If there is no argument 
list this pointer is 0, 
and BEGARGS/ENDARGS are 
used for the ARG string. 

SYSFUNRT location, which: 

* contains a zero on entry 

* will be unchanged if 

* no result is returned f 

* will contain the address of an L 

* EVALBLOK if a result is returned. 
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The argument list consists of an Adlen (Address/Length) pair for each 
argument string. The final value pair is followed by two fullwords 
containing -1 (that is, hex FFFFFFFF). There is no limit to the number of 
strings when the interpreter is called, but note that the interpreter itself 
will only provide from zero to ten argument strings. 

If the argument list is given, the simple argument string (as defined by 
BEGARGS and ENDARGS) is not used for the ARG instruction or the ARG 
built-in function. 

Note: The argument list and the strings it defines must be in privately 
owned storage. This means that the interpreter need not copy the data 
strings before using them (as has to be done for the BEGARGS/ENDARGS 
string, when it is used). 

The result of a subroutine or function call using the six-word Extended 
Plist is returned in a block of USER storage allocated by DMSFREE and 
which has the following storage assignments and values: 

*— DSECT for the returned data block-* 


EVALBLOK 

EVBPAD1 

DSECT 

DS 

F 

Reserved 

EVSIZE 

DS 

F 

Total block size in DW's 

EVLEN 

DS 

F 

Length of Data (in bytes) 

EVBPAD2 

DS 

F 

Reserved — should be set to 0 

EVDATA 

DS 

C. . . 

The returned character string 


A result may only be returned if the called routine ends cleanly, with a 
Register 15 return code of 0. 


The File Block 


This block is pointed to by word4 of the Extended Plist described above. It 
is only needed if the interpreter is to execute a non-EXEC file or is to 
execute from storage, or is to have an address environment that is not the 
same as its filetype. If it is not required, word4 of the Extended Plist should 
be set to 0. 
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FBLOK DS 
DC 


OF 

CL8'filename' 


DC CL8'filetype' 


DC 

DC 


CL2*filemode* 
H'extlen' 


** File block 
logical name of program 

(also physical name if not 
in storage). 

logical type of program (also 
default destination for 
commands — blanks or "EXEC" 
cause commands to be 
passed to CMS environment). 
normally '* ' or ' ' 

length of extension block 

* in fullwords (may be 0) . 

*-> Extension block starts here, 

*-> In-storage program definition 

* Following two words should be 0 if extlen >= 2 and 

* in-storage program is not supplied. 

DC AL4(PROG) -> Start of program 

* descriptor list. 

DC AL4(PGEND-PROG) Length of same in bytes. 

*-> Initial Address environment (overrides default from 
filetype). 

if not used and extlen = 4. 

The initial environment. 

May be a PSW for non-SVC 
subcommand call. 

Name of an initial environment 
for non-SVC subcommand call. 


Should be set to 2F'0' 
DC CL8'environment' 


DC CL8 ' envname 1 


■> End of FILEBLOK 


The descriptor list for an in-storage program looks like this: 


** Descriptor list for in-storage program 


PROG 

DS 

OF 

** In storage program ** 


DC 

A(linel),F'lenl' 

Address, 

length 

of 

line 1 


DC 

A(line2) ,F*len2 1 

Address, 

length 

of 

line 2 


DC 

A(lineN),F'lenN' 

Address, 

length 

of 

line N 

PGEND 

EQU 

★ 






Notes: 

1. The in-storage program lines need not be contiguous, since each is 
separately defined in the descriptor list. 

2. For in-store execution, the Filename is still required in the file block, 
since this determines the logical program name. The Filetype similarly 
sets the default command environment, unless it is explicitly overridden 
by the name in the extension block. 

3. If the extension length is > = 4 Fullwords, the 3rd and 4th fullwords 
form an 8-character environment address that overrides the default 
address set from the Filetype in the file block; and thus forms the initial 
ADDRESS to which commands will be issued. This new address may be 
all characters (for example, blank, CMS, or some other environment 
name), or it may be a PSW for non-SVC subcommand execution - 
described on page 158. It may be cleared to 8X‘00’ if not required. 

4. If the extension length is > = 6 Fullwords, the 5th and 6th fullwords 
form an 8-character environment name that is used for the default 
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address. The 4th and 5th Fullwords are used as a PSW for non-SVC 
subcommand execution - described on page 158. The environment name 
will be returned by PARSE SOURCE and the ADDRESS() built-in 
function and the PSW in the 4th and 5th Fullwords will be used to 
invoke subcommands. 


Function Packages 

Functions and subroutines may be written in REXX, or in any other 
language that has an interface that conforms to the six-word Extended Plist 
described above. Those routines not written in REXX may be supplied 
simply as a file with a filetype of MODULE. For a further improvement in 
performance, routines which are called frequently may be loaded as 
Nucleus Extensions, or placed in a Function Package. 

A function package contains the code for functions that are candidates for 
loading as nucleus extensions. The first time a function in one of the three 
packages known to the interpreter (RXUSERFN and RXLOCFN and 
RXSYSFN) is invoked, a call to the package with a LOAD request causes 
the package to load itself as a Nucleus Extension (if it is not already in 
storage). The entry point to the particular function required is then 
declared as a Nucleus Extension by the package. On subsequent calls, the 
code for the function is directly available using SVC 202 and the extra 
processing for loading the package MODULE from disk is avoided. The 
functions in a package will usually share common code and subroutines. 

For an example of a function package, see “Appendix B: Example of a 
Function Package” on page 169. 

Refer to page 71 for the full search order of external routines. 

All external routines are invoked using the six-word Extended Plist defined 
above. If the called routine is not an EXEC or Macro (that is, will not be 
processed by EXEC), then word4 is zero. Word5 points to the list of 
arguments, and word6 points to a location that may be used to return the 
address of an EVALBLOK which will contain the result of the function or 
subroutine. If the routine is being called as a subroutine (rather than as a 
function), so that it need not return a result, then the top bit of R0 will be 
set to indicate this. Otherwise the routine should return a result - the 
interpreter will raise an error if it does not. 

During calculation of the result, the routine may use the argument strings 
(which reside in USER storage owned by the interpreter) as work areas, 
without fear of corrupting internal REXX values. 

External function packages must be able to respond to a call of the form: 
RXnameFN LOAD RXfname 

(which is issued using just the Tokenized Plist, with Register 1 Byte 0 being 

XW). 
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If, when the package RXnameFN is invoked with this request, RXfname is 
contained within the package, RXnameFN will: 

• load itself, if necessary 

• install the NUCEXT entry point for the function 

• return with a return code 0; 

otherwise, the return code will be 1. This allows the function packages and 
entry points to be automatically loaded by the interpreter when necessary. 


Non-SVC Subcommand Invocation 


When a command is issued to an environment, there is an alternative 
non-SVC fast path available for issuing commands. This mechanism may be 
used if an environment wishes to support a minimum-overhead subcommand 
call. 

The fast path is used if the current eight character environment address has 
the form of a PSW (signified by the fourth byte being X‘00’). This address 
may be set using the Extended Plist (see above) or by normal use of the 
ADDRESS instruction if the PSW has been made available to the EXEC in 
some other way. Note that if a PSW is used for the default address, the 
PARSE SOURCE string will use ? as the name of the environment unless 
an environment name has also been provided. 

The definition of the interface follows: 


1. the interpreter will pass control to the routine by executing an LPSW 
instruction to load the eight-byte environment address. On entry to the 
called program the following registers are defined: 


Register 0 Extended Plist as per normal subcommand call. First word 
contains a pointer to the PSW used, second and third 
words define the beginning and end of the command string, 
and the fourth word is 0. 

Register 1 Tokenized Plist. First doubleword will contain the PSW 
used, second doubleword is 2F‘-1\ Note that the top byte 
of Register 1 does not have a flag. 


Register 2 is the original Register 2 as encountered on the initial 

entry to the interpreter's external interface. This register is 
intended to allow for the passing of private information to 
the subcommand entry point, typically the address of a 
control block or data area. This register is only safe if the 
EXEC is invoked via a BALR to the entry point contained 
at label AEXEC in NUCON, otherwise this register is 
altered by the SVC processor. 


Register 13 points to an 18 Fullword save area. 
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Register 14 contains the return address. 

(All other registers are undefined.) 

2. It is the called program's responsibility to save Registers 9 through 12 
and to restore them before returning to the interpreter. All other 
registers may be used as work registers. 

3. On return to the interpreter, Registers 9 through 12 must be unchanged 
(see Item 2 above), and Register 15 should contain the return code 
(which wilj be placed in the variable RC as normal). Contents of other 
registers are undefined. The interpreter will set the storage key and 
mask that it requires. 

Note: The EXECCOMM subcommand entry point is always set up when 

execution of a REXX program begins, even if EXEC is called via BALR. 

This results in a subcommand block being added to the SUBCOM chain. 


Direct Interface to Current Variables 

The interpreter provides an interface whereby called commands may easily 
access and manipulate the current generation of REXX variables. 

Variables may be inspected, set, or dropped; and if required all active 
variables may be inspected in turn. The manipulation of internal work 
areas is carried out by the interpreter's own routines: user programs do not 
therefore need to know anything of the structure of the variables' access 
method (which includes complex binary trees, etc.). Names are checked for 
validity by the interface code, and optionally substitution into compound 
symbols is carried out according to normal REXX rules. Certain other 
information about the program that is running is also made available 
through the interface. 

The interface works as follows: 

When the interpreter starts to interpret a new program it first sets up a 
subcommand entry point called EXECCOMM. When a program 
(Command, Subcommand, or external Routine) is invoked by the 
interpreter, it may in turn use the current EXECCOMM entry point to Set, 
Fetch, or Drop REXX variables, using the interpreter's internal 
mechanisms. Part of the interpreter carries out all changes to pointers, 
allocation of storage, substitution of variables in the name, etc. and hence 
isolates user programs from the internal mechanisms of the interpreter. 

To access variables, EXECCOMM is invoked using both the Tokenized and 
the Extended Plist (see also page 153). SVC 202 is issued with R1 pointing 
to the normal Tokenized Plist, and the high order byte of R1 set to X‘02\ as 
this is a subcommand call. 

The R1 Plist: Register 1 must point to a Plist which consists of the eight 
byte string EXECCOMM . 
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The RO Plist: Register 0 must point to an Extended Plist. The first word 
of the Plist must contain the value of Register 1 (without the flag in the 
high order byte). No argument string may be given, so the second and third 
words must be identical (for example, both 0). The fourth word in the Plist 
must point to the first of a chain of one or more request blocks, see below. 

On return from the SVC, Register 15 will contain the return code from the 
entire set of requests. The possible return codes are: 

0 (Positive). Entire Plist was processed. Register 15 is the composite OR 
of Bits 0-5 of the SHVRET bytes (see below.) 

-1 Invalid entry conditions (for example, BEGARGS = ENDARGS, or 
EXECCOMM is being called when the interpreter is active). 

-2 Insufficient storage was available for a requested SET. Processing was 
aborted (some of the request blocks may remain unprocessed - their 
SHVRET bytes will be unchanged). 

-3 (from SUBCOM). No EXECCOMM entry point found; for example, not 
called from inside a REXX program. 


The Request Block (SHVBLOCK) 

Each request block in the chain must be structured as follows: 

******************************************************** 

* SHVBLOCK: layout of shared-variable Plist element 
******************************************************** 

SHVBLOCK DSECT 


SHVNEXT 

DS 

A 

Chain pointer (0 if last block) 

SHVUSER 

* 

DS 

F 

Available for private use, except 
during "Fetch Next". 

SHVCODE 

DS 

CL1 

Individual function code 

SHVRET 

DS 

XL1 

Individual return code flags 


DS 

H 1 0' 

Not used, should be zero 

SHVBUFL 

DS 

F 

Length of 'fetch* value buffer 

SHVNAMA 

DS 

A 

Address of variable name 

SHVNAML 

DS 

F 

Length of variable name 

SHVVALA 

DS 

A 

Address of value buffer 

SHVVALL 

DS 

F 

Length of value 

SHVBLEN 

EQU 

SPACE 

♦-SHVBLOCK (length of this block = 32) 

Figure 3 

(Part 1 of 2). 

Request block(SHVBLOCK) 
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* 

* Function Codes (SHVCODE): 

* 

* (Note that the symbolic name codes are lowercase) 

SHVSET EQU C'S* Set variable from given value 

SHVFETCH EQU C'F 1 Copy value of variable to buffer 

SHVDROPV EQU C'D' Drop variable 

SHVSYSET EQU C's' Symbolic name Set variable 

SHVSYFET EQU C'f' Symbolic name Fetch variable 

SHVSYDRO EQU C'd* Symbolic name Drop variable 

SHVNEXTV EQU C'N' Fetch "next" variable 

SHVPRIV EQU C*P* Fetch private information 

SPACE 

* 

* Return Code Flags (SHVRET): 

* 

SHVCLEAN EQU X'OO' Execution was OK 

SHVNEWV EQU X*01* Variable did not exist 

SHVLVAR EQU X'02' Last variable transferred (for "N") 

SHVTRUNC EQU X'04' Truncation occurred during "Fetch” 

SHVBADN EQU X 1 08 1 Invalid variable name 

SHVBADV EQU X'lO* Value too long (EXEC 2 only) 

SHVBADF EQU X'80 * Invalid function code (SHVCODE) 

* ____________ 

Figure 3 (Part 2 of 2). Request block(SHVBLOCK) 

A typical calling sequence using fully relocatable (NUCXLOADable) and 
read-only code might be: 


LA 

R0,EPLIST 

-> Extended Plist, 

as 

above 

LA 

R1,=CL8'EXECCOMM' 

(normal Plist) 



I CM 

R1,B 1 1000 *,=X'02' 

Insert "subcommand 

call" flag 

SVC 

202 

Issue SVC 



DC 

AL4(1) 

Always return to next 

instruction 

LTR 

R15,R15 

Test return code 



BM 

DISASTER 

Where to go if bad 

return code 


* Execution was OK (RC>=0) 

Function Codes (SHVCODE) 

Three function codes (S, F, and D) may be given either in lowercase or in 

uppercase: 

Lowercase (The Symbolic interface). The names must be valid REXX 
symbols (in mixed case if desired), and normal REXX 
substitution will occur in compound variables. 

Uppercase (The Direct interface). No substitution or case translation 
takes place. Simple symbols must be valid REXX variable 
names (that is, in uppercase, and not starting with a digit or a 
period), but in compound symbols any characters (including 
lowercase, blanks, etc.) are permitted following a valid REXX 
stem. 
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Note: The Direct interface, which is also provided (in part) by EXEC 2, 
should be used in preference to the Symbolic interface whenever generality 
is desired. 

The Other function codes, N and P, must always be given in uppercase. The 
specific actions for each function code are as follows: 

S and s Set variable. The SHVNAMA/SHVNAML adlen describes the 
name of the variable to be set, and SHVVALA/SHVVALL 
describes the value which is to be assigned to it. The name is 
validated to ensure that it does not contain invalid characters, 
and the variable is then set from the value given. If the name is a 
stem, all variables with that stem are set, just as though this was 
a REXX assignment. SHVNEWV is set if the variable did not 
exist before the operation. 

F and f Fetch variable. The SHVNAMA/SHVNAML adlen describes the 
name of the variable to be fetched. SHVVALA specifies the 
address of a buffer into which the data is to be copied, and 
SHVBUFL contains the length of the buffer. The name is 
validated to ensure that it does not contain invalid characters, 
and the variable is then located and copied to the buffer. The 
total length of the variable is put into SHVVALL, and if the value 
was truncated (because the buffer was not big enough) the 
SHVTRUNC bit is set. If the variable is shorter than the length 
of the buffer, no padding takes place. If the name is a stem, the 
initial value of that stem (if any) is returned. 

SHVNEWV is set if the variable did not exist before the 
operation, and in this case the value copied to the buffer is the 
derived name of the variable (after substitution etc.) - see page 13. 

D and d Drop variable. The SHVNAMA/SHVNAML adlen describes the 
name of the variable to be dropped. SHVVALA/SHVVALL are 
not used. The name is validated to ensure that it does not contain 
invalid characters, and the variable is then dropped, if it exists. If 
the name given is a stem, all variables starting with that stem are 
dropped. SHVNEWV is set if no variables were affected by the 
operation. 

N Fetch Next variable. This function may be used to search 

through all the variables known to the interpreter (that is , all 
those of the current generation, excluding those “hidden” by 
PROCEDURE instructions). The order in which the variables are 
revealed is not specified. 

The interpreter maintains a pointer to its list of variables: this is 
reset to point to the first variable in the list whenever 1) a host 
command is issued, or 2) any function other than “N” is executed 
via the EXECCOMM interface. 
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Whenever an N (Next) function is executed the name and value of 
the next variable available are copied to two buffers supplied by 
the caller. 

SHVNAMA specifies the address of a buffer into which the name 
is to be copied, and SHVUSER contains the length of that buffer. 
The total length of the name is put into SHVNAML, and if the 
name was truncated (because the buffer was not big enough) the 
SHVTRUNC bit is set. If the name is shorter than the length of 
the buffer, no padding takes place. The value of the variable is 
copied to the users buffer area using exactly the same protocol as 
for the Fetch operation. 

If SHVRET has SHVLVAR set, the end of the list of known 
variables has been found, the internal pointers have been reset, 
and no valid data has been copied to the user buffers. If 
SHVTRUNC is set, either the name or the value has been 
truncated. 

By repeatedly executing the N function (until the SHVLVAR flag 
is set) a user program may locate all the REXX variables of the 
current generation. 

P Fetch private information. This interface is identical to the F 

fetch interface, except that the name refers to certain fixed 
information items that are available. Only the first letter of each 
name is checked (though callers should supply the whole name), 
and the following names are recognized: 

ARG Fetch primary argument string. The first argument 

string that would be parsed by the ARG instruction is 
copied to the user's buffer. 

SOURCE Fetch source string. The source string, as described 
for PARSE SOURCE on page 47, is copied to the 
user's buffer. 

VERSION Fetch version string. The version string, as 

described for PARSE VERSION on page 48, is copied 
to the user's buffer. 

Notes: 

1. Only the S (Set) and F (Fetch) functions are supported by EXEC 2. 

Other requests will be rejected. 

2. The interface is only enabled during the execution of commands 
(including CMS subcommands) and external routines (functions and 
subroutines). An attempt to call the EXECCOMM entry point 
asynchronously will result in a return code of -1 (Invalid entry 
conditions). 
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3. While the EXECCOMM request is being serviced, interrupts will be 
enabled for most of the time. 


EXECFLAG External Control Byte 

The interpreter is affected by and may alter the global flags held in the 
EXECFLAG byte in NUCON (page 0 of your CMS system). These are used 
for external control of tracing and also to permit interrupting execution. 

The following equates are defined: 

****** t ************************************** *********** 

* Equates for EXECFLAG in NUCON * 

******************************************************* 

EXECFLAG DC IX'00' EXEC FLAGS 

EXECRUN EQU X' 80 ' EXEC COMMAND RUNNING 

EXECSTOP EQU X'40' HALT interpreter HAS BEEN RECOGNIZED. 

EXECMASK EQU X'20* HALT interpreter ENABLED. 

EXECHALT EQU X 1 10' HALT interpreter HAS BEEN ISSUED. 

EXECTRST EQU X ' 08 1 TRACE CAN BE RESET BY XEDIT. 

EXECFL04 EQU X'04' (reserved) 

EXECTMSK EQU X'02* TRACE START ENABLED. 

EXECTRAC EQU X'01* EXEC TRACE REQUESTED. 

Details of the use of each flag by the interpreter are as follows: 

EXECRUN This flag is defined only for CMS EXEC programs, and 

therefore is neither inspected nor altered by the interpreter 
or its interface. 

EXECSTOP This flag is set by the REXX interface (DMSEXI) when an 
EXECHALT request is detected and has been honored. On 
exit from the interpreter, this bit indicates that the program 
stack should be cleared, as the interpreter was halted 
(probably asynchronously). On re-entry to DMSEXI this bit 
indicates that the EXECHALT flag has been used 
previously and may now be cleared (together with the 
EXECSTOP bit). (Interlock for EXECHALT.) 

EXECMASK Mask for EXECHALT. EXECHALT takes effect only if this 
bit is set. This bit is set on entry to DMSEXI. 

EXECHALT Request to halt execution of all active REXX programs. 

Takes effect only if EXECMASK is 1. This bit is cleared on 
entry to DMSEXI if EXECSTOP is set, and also if detected 
normally but SIGNAL ON HALT is enabled. This bit is 
cleared by the interpreter if SIGNAL ON HALT is enabled 
and takes effect. 

EXECTRST EXECTRAC has been accepted. On return to command 

level, CMS and XEDIT will only turn off EXECTRAC if this 
bit is ON. (Interlock for EXECTRAC.) 
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EXECTMSK 

EXECTRAC 


Mask for EXECTRAC. EXECTRAC takes effect only if this 
bit is set. This bit is set on entry to DMSEXI. 

If this bit changes from 0 to 1 or from 1 to 0, the interpreter 
will force interactive tracing on or all tracing off 
respectively. See page 119 for further details. This bit is 
neither set nor reset by the interpreter, except that the bit 
is cleared on return to CMS or XEDIT command level after 
it has been acknowledged by the setting of EXECTRST. 
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REXX is unusual in being an interpreted structured language. Because of 
this REXX has required some fairly complicated coding techniques to 
improve performance. These include: 

• Variable names are held in a two-level binary tree to provide fast 
lookup and an efficient implementation of the PROCEDURE EXPOSE 
function. 

• The position in the data of all labels is saved in a look-aside buffer 
arranged in most-recently-used order: this considerably improves the 
performance of subroutine and internal function calls. Accesses to 
built-in and external routines are similarly recorded and reordered for 
improved performance. 

• The internal form of all clauses is saved in a second look-aside buffer to 
save the need for parsing each clause each time it is executed, giving 
speed improvements of a factor of two in many loops. This look-aside is 
not started until the first CALL, INTERPRET, repetitive DO, or label is 
found. This look-aside also means that the overhead of including 
comments on a line with an instruction is negligible except for the 
storage they take up and the initial read-in time. Comments on a 
separate line mat affect performance, but these may be removed in the 
executable form by EXECUPDT. 

• Special look-aside information is kept for DO-loops to minimize loop 
overhead. 

• Parsing is optimized for mixed case data. PARSE ARG and PARSE 
PULL are therefore slightly faster than ARG and PULL. 

Where possible, the executable form of REXX programs should be in 
V-format. This minimizes execution time, main storage use (paging), and 
disk space. (Note: if EXECUPDT is used, the library files are F-format but 
the executable file is V-format.) 

Wherever possible, REXX programs should be written in mixed case 
(especially comments). This maximizes reading speed and minimizes human 
errors due to misreading data, and so improves the performance of the 
human side of the REXX programming operation. 

There is no particular area in the interpreter that can be described as a 
bottleneck. However, any external call may incur significant system 
overheads. High precision numbers should be avoided unless truly needed. 
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TITLE 'USERFN: Sample model for user function package' 


* The first part of this example deals with obtaining free 

* storage and moving the rest of the program into that storage 

* as a nucleus extension. The code just loaded (from FREEGO 

* label to the table before FUNC1) then responds to the 

* original call and successive calls to RXUSERFN. Calls to 

* load a user function are handled by setting up their entry 

* points as nucleus extensions. 

* In order to set up new user functions, the user must add an 

* entry in the FUNLIST table and add the code following the 

* other functions. 


* 

USERFN 

CSECT 

USING 

USING 

* 

*,R12 

NUCON,0 



LR 

RIO,R14 

Save return address 

* 

SLR 

R2,R2 

Assume it's NUCEXT 
"RXUSERFN" only. 


CLI 

ARGl(Rl),X 1 FF ' 

Any arguments? 


BE 

GOLOAD 

Br if not - go install 


CLC 

ARG1(8,R1),=CL8 1 

LOAD' Is this explicit load? 


BNE 

BADPL 

Br if not - go complain 

* 

Note: 

We do not have 

to handle RESET because the 

* 

SPACE 

package has not 

1 

yet been loaded 

*-> LOAD 

request, so check function name against FUNLIST 

SPACE 1 


LA 

R4,LENTRY 

Length of FUNLIST entry 


LA 

R2,FUNLIST 

Start of function table 


LA 

R5,EFUNLIST 

End of function table 

CHECK 

EQU 

* 



CLC 

ARG2(,R1),FUNLNAME(R2) Names match? 

* 

BE 

GOLOAD 

Br if yes - go do 
appropriate NUCEXTing. 


BXLE 

R2,R4,CHECK 

Continue testing if more 


LA 

R15,1 

Indicate function not found 


BR 

SPACE 

RIO 

1 

Not in list - return 


*=> NUCEXT "RXUSERFN" as well as specific function (e.g. if 

* LOAD specified on invocation). 

SPACE 1 
GOLOAD EQU * 

LA RO,FREELEND Length of code in DWs 

* Get the storage 
DMSFREE DWORDS=(0),TYPE=NUCLEUS,ERR=NOSTORE 


LA 

R8,FREEGO 

Start of free storage code 

L 

R9,=A(FREELEN) 

Get length in bytes 

LR 

R7,R9 

Copy length for MVCL 

LR 

R4,R9 

Save for later use 

LR 

R3,R1 

ii it 

LR 

R6 ,R1 

Free storage area start 

SPKA 

0 

Set nucleus key 

MVCL 

R6 ,R8 

Move code to free storage 

ST 

R3,NLADDR 

Entry point address 
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ST 

R3,NLSTART 

Start address 

MV I 

NLFLAG,SYSTEM+SERVICE Request service call 

ST 

R4,NLLEN 

Length 

LA 

R1,NLIST 

-> PLIST 

SVC 

CMS202 


DC 

AL4{1) 

Fall through if error 

LTR 

R15,R15 

Did everything go smoothly? 

BNZR 

RIO 

No, return directly. 

See if we have a function.... 


LTR 

R2,R2 

Install "RXUSERFN" only? 

BZR 

RIO 

Br if yes - return to caller 

R15 already 0 from above. 

. ..Use to clear fields 

ST 

R15,NLSTART 

..start address 

ST 

R15,NLLEN 

..length 

MVI 

NLFLAG,SYSTEM 

.. no service calls! 

SPACE 

1 


! points to 

FUNLIST entry to be 

installed. 

! points to 

start of NUCXLOADed 

area. 

A 

R3,FUNOFFS(,R2) 

Calculate true start address 

ST 

R3,NLADDR 

Add to startup PSW 

MVC 

NLNAME,FUNLNAME(R2) 

Copy startup name 

Issue SVC. 

. . 


SVC 

CMS202 


DC 

AL4(1) 

Immediate exit on error 

BR 

RIO 

Return to caller 

DROP 

R12 


SPACE 

3 


LTORG 

! 


TITLE 

*USERFN: Code residing in free storage* 


* The following code resides in free storage, and is capable * 

* of replying to LOAD or RESET. * 

* A LOAD call results in the identifying of the functions * 

* passed as parameters following LOAD as entry points in * 

* RXUSERFN. * 

* A RESET service call from NUCXDROP will turn the functions * 

* OFF. A PURGE service call is ignored. * 

* - * 


FREEGO 

* 


STARTCOD 


CHK4ARGS 


* 


SPACE 

2 


DS 

0D 

Force doubleword alignment 
of free-loaded code. 

USING 

*, R12 


B 

STARTCOD 


DC 

CL8 *>USERFN< * Eye-catcher for storage dump 

EQU 

* 


LR 

RIO,R14 

Save return address 

CLC 

ARGl(8,R1) 

, =CL8* LOAD * Is this a load? 

BE 

CHK4ARGS 

Yes, check for any args 

CLC 

ARGl(8,R1) 

,=CL8'RESET' Reset ? 

BE 

DOOFF 

Yes, turn off functions 

SLR 

R15,R15 

In case of service call 

CLM 

R1,B'1000' 

,=X'FF' Is it an abend call ? 

BER 

R14 

Br if yes - quick quit 

LA 

R15,4 

No, set error RC 

BR 

R14 

. . and return 

SPACE 

1 


EQU 

* 


LA 

R15,1 

Set possible return code 

CL I 

ARG2(Rl),X 

' FF’ Any arguments passed? 

BER 

R14 

No, error (already loaded) 


* AUTOLOAD: switch on selected function * 


★ * 
* 'LOAD' request. Check function name against FUNLIST. * 


170 VM/SP System Product Interpreter Reference 







* 

* 


Only turn on the requested (autoload) function 


* 

* 

* 


★ 



SPACE 

1 



PUSH 

USING 

Save USING status 


USING 

DNUCX,R13 

Use save area for PLIST 

AUTOLOAD 

EQU 

* 



MVC 

DNLIST(LNLIST),NLIST Move skeleton to work area 


LR 

R3 , R1 

Save old plist pointer 


LA 

R4,LENTRY 

Length of FUNLIST entry 


LA 

R5,EFUNLIST 

End of function table 


LA 

R2 t FUNLIST 

Start of function table 


LA 

R15,1 

Set error return code 

CHECKl 

EQU 

* 



CLC 

ARG2(,R3),FUNLNAME(R2) Check against name 


BE 

TURNON 

Found - turn function on 


BXLE 

R2,R4,CHECKl 

Loop for another check 


BR 

RIO 

Return with RC = 1 


SPACE 

1 


TURNON 

EQU 

* 



MVC 

DNLNAME,FUNLNAME(R2) Copy startup name 


LA 

Rl,DNLIST 

-> PLIST 

* See if 

function is already a 

nucleus extension 


LNR 

R15,R15 

-1 


ST 

R15,DNLADDR 

Query form of NUCEXT plist 


SVC 

CMS202 



DC 

AL4(1) 

Fall through if error 


LTR 

R15,R15 

Exists? 


BZR 

RIO 

Yes, immediate return 


L 

R6,FUNOFFS(,R2) 

Load address offset 


ALR 

R6,R12 

True start address 


ST 

R6,DNLADDR 

Add to startup PSW 

* Issue SVC. 

. . 



SVC 

CMS202 



DC 

AL4 (1) 

Ignore errors 


BR 

RIO 

Return 


POP 

USING 

Restore USING status 


SPACE 

1 


************************************************************** 

* RESET 

call: 

switch off functions 

************************************************************** 

DOOFF 

EQU 

* 



LA 

R5,FUNLIST 

-> to list 


LA 

Rl,NLIST 

-> PLIST 

FUNLOOP 

EQU 

* 



LT 

R15,FUNOFFS(R5) 

Any more to cancel? 


BZR 

RIO 

0 = all done ... Get out 


MVC 

NLNAME(8),FUNLNAME(R5) Copy startup name 

* Issue SVC. 

. . 



SVC 

CMS202 



DC 

AL4(1) 

Ignore errors 

* 

(we ignore errors e.g. 

: function already cancelled) 


LA 

R5,LENTRY(,R5) 

-> next item in FUNLIST 


B 

FUNLOOP 



EJECT 



* PLIST for 

invoking 'NUCEXT* 

(also used directly as the 

* the 

CANCEL 

plist) 


NLIST 

DS 

0D 

NUCEXT Plist 


DC 

CL8'NUCEXT' 

Name 

NLNAME 

DC 

CL8'RXUSERFN' 

Function name 


DC 

X ' FF' 

System mask enabled 

NLKEY 

DC 

X 1 04' 

System key 

NLFLAG 

DC 

AL1(SYSTEM) 

NUCEXT Flag 


DC 

X'OO* 

Spare flags 

NLADDR 

DC 

A (0) 

Entry point address 
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NLSTART 

NLLEN 

LNLIST 


DC 

DC 

DC 

EQU 


AL4(*-*) 
A(0) 

F * 0 1 
*-NLIST 


SPACE 5 


private 
Start address 
Length 

Length of list 


* List of functions included in this pack, with their offsets 


FUNLNAME EQU 
FUNOFFS EQU 
FUNLIST DC 
LENTRY EQU 
DC 
DC 

EFUNLIST EQU 
DC 


4,8 Offset & length of name 

0,4 Offset to the routine 

A(FUNCl-FREEGO),CL8*RXUSER1 1 

*-FUNLIST Length of a single entry 

A(FUNC2-FREEGO),CL8 1 RXUSER2 * 

A(FUNC3-FREEGO),CL8 * RXUSER3 ' 

* End of the funlist proper 

A(*-*) End fence 


EJECT 

-I-I-f-I-I-I-I-i-I-!-i-!-I-I-I-I-I-I—1-I-I-h — H-I-I-I-1-I-I-h 

* A sample user written function is shown below. As many 

other functions can be added as the user desires. The only 
restriction is that the module must fit in the transient 
area (where it runs before loading itself as a nucleus 
extension). 

The normal order is to obtain an EVALBLOK (here done by 
the GETBLOK routine), do the function and put the result 
in the EVALBLOK, and finally to complete the EVALBLOK and 
return (here done by the EBLOCK routine). 

—i—i—I—H-1—I—-I—I-1—I—-I—I—I—I-•-1-1—H-1-1-1-1—I—I-1—H-1—H-h 

SPACE 2 

1 USERFN: USER1 - User function 1* 

This function simply returns the first passed parameterl 
EQU 


* 

★ 

FUN Cl 


USING *,R12 
LR RIO,R14 
LR R13,R0 
USING EFPLIST,R13 
L R11,EARGLIST 

MVC SAVEFRET,EFUNRET 
DROP R13 

USING PARMBLOK,R11 
L R1,PARM1LEN 

LR R3,R1 
BAL R14,GETBLOK 
USING EVALBLOK,R5 


Tell assembler of base 
Save return address 
Get copy of R0 
Addressing for the plist 
Get pointer to arg list 
Save function return addr 
Done with this for now 
Tell assembler 
Returned data length 
Save it for later 
Go get EVALBLOK 
Tell assembler 


* other processing for function 1 would be here 

* 


*************************************************************** 
* * 

* 
* 

*************************************************************** 
L R15,PARM1ADR 

EX R3,MOVEIT Move the data 

LA R15,0 Set good return code 

B EBLOCK Complete EVALBLOK & return 

MOVEIT MVC EVDATA(0),0(R15) Move user parm to eval block 

SPACE 2 

* 'USERFN: USER2 - User function 2' 

FUNC2 EQU * 

*************************************************************** 
it * 

* code for user function 2 goes herel * 

* * 

*************************************************************** 
SPACE 2 

* 'USERFN: USER3 - User function 3' 
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FUNC3 EQU * 

*************************************************************** 
* * 

* code for user function 3 goes herel * 

* * 

*************************************************************** 
TITLE 1 USERFN: Common get EVALBLOK subroutine' 


* This subroutine obtains an EVALBLOK. * 

* The assumed input is: * 

* - Rl: length of EVDATA (return data length) * 

* - R14: return address * 

* * 


* The output is: 

* - RO, Rl, & R2 undefined 

* - R4: number of doublewords in entire EVALBLOK 

* - R5: address of the EVALBLOK 

* - R15: undefined 

* - other registers are unchanged. 

* 


* 

* 

* 

* 

* 

* 

* 


* If storage is not available, an error message is displayed * 

* and return is taken to the caller with a non-zero return * 

* code. * 

* ___ - ___ 


GETBLOK 


* 


* 


* 


SPACE 2 
EQU * 

BALR R2,0 Establish base register 

USING * ,R2 Tell assembler 

LA RO,EVCTLEN+7( f Rl) Add in overhead + rounding 

SRL RO,3 Make it doublewords 

LR R4, RO Return number of doublewords 

in entire EVALBLOK. 


DMSFREE DWORDS=(0),ERR=NOSTORE Get the storage 
LR R5,R1 Save A(EVALBLOK) 

Now clear the storage block 


LR 

R15,R3 

LR 

RO ,R5 

LR 

R1,R4 

SLL 

Rl, 3 

LA 

R3,0 

MVCL 

RO ,R2 

LR 

R3,R15 

BR 

R14 

DROP 

R2 

TITLE 

'USERFN 


Save R3 

Addr of storage block in RO 
Length of storage in Rl 
Make it bytes I 
length to 0, pad of '00'x 
Clear the block 
Restore R3 
Return to caller 
Done with this guy 
Common complete EVALBLOK routine' 


* 


* At this point the EVALBLOK is filled in. The registers * 

* are assumed to be as follows: * 

* R3 - the number of bytes of data to be returned 

* R4 - the size (in doublewords) of the entire EVALBLOK * 

* R5 - the address of the EVALBLOK * 


SPACE 1 
EBLOCK EQU * 

BALR R12,0 
USING *,R12 
USING EVALBLOK,R5 
ST R4,EVSIZE 
L R4,SAVEFRET 

ST R5,0(R4) 

ST R3,EVLEN 
BR RIO 

DROP R5 
TITLE 


Set base register 
Tell assembler 
Addressing for EVALBLOK 
Total block size (DW's) 

Get back return address 
Pass address back to caller 
Set it in EVALBLOK 
Abandon ship 


* 


Common Error Processing Routines' 


* Error handling routines. 
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* Note that in order to avoid the generation of relocatable * 

* address constants, the TYPLIN PLIST is ’’hand built" rather * 

* than using WRTERM. * 


*_ 

SPACE 

3 



BADPL 

EQU 

* 


Something's wrong with PLIST 


BALR 

R12,0 


Load base for this code 


USING 

* , R12 


Tell assembler of this 


LA 

R1,MSG1 


Get message address 


LA 

R2,L'MSG1 


Get message length 


B 

DISPMSG 


Go display the message 


SPACE 

1 



NOSTORE 

EQU 

* 


DMSFREE not successful 


BALR 

R12,0 


Load base for this code 


USING 

* ,R12 


Tell assembler of this 


LA 

R1,MSG2 


Get message address 


LA 

R2 ,L'MSG2 


Get message length 

DISPMSG 

EQU 

* 




BALR 

R12,0 


Load base for this code 


USING 

*,R12 


Tell assembler of this 


STCM 

R1,B'0111',TYPBUFF Set it in PLIST 


STH 

R2,TYPLEN 


Set it in PLIST 


01 

TYPLIN+13,X' 

40* 

Request error message edit 


LA 

Rl,TYPLIN 


Point at PLIST 


SVC 

CMS202 


Give it to CMS 


DC 

AL4(1) 


Ignore errors 

N0DISPL1 

EQU 

* 




LA 

R15,4 


Set non-zero return code 


BR 

RIO 


Return 


SPACE 

1 



TYPLIN 

DC CL8'TYPLIN',X'01',AL3(0),C'B',X'00',AL2(0) 

TYPBUFF 

EQU 

TYPLIN+9,3 



TYPLEN 

EQU 

TYPLIN+14,2 



MSG1 

DC 

C'DMSRUF070E 

Invalid parameter* 

MSG2 

DC 

C 1 DMSRUF450E 

Machine storage exhausted' 


SPACE 

2 



SAVEFRET 

DS 

F 


Function return address 


ORG 

r 




SPACE 

2 




LTORG 



Literal pool 


TITLE 

' USERFN : Common 

symbolic assignments' 


SPACE 

1 



CMS202 

EQU 

202 


CMS SVC 202 

ARG1 

EQU 

8,8 


First argument 

ARG2 

EQU 

16,8 


Second argument 


REGEQU 




DS 

OD 


Get to doubleword boundary 

FREELEN 

EQU 

*-FREEGO 


Bytes of free store code. 

FREELEND 

EQU 

(*-FREEGO+7)/8 

Doublewords of. free store 

* 




code. 


SPACE 

1 



* NUCEXT 

PLIST 

Flags: 



SERVICE 

EQU 

X' 40' 



SYSTEM 

EQU 

X' 80' 




SPACE 

2 



*— DSECT for the function 

plist - 

EFPLIST 

DSECT 




ECOMVERB 

DS 

F 


COMVERB pointer 

EBEGARGS 

DS 

F 


pointer to argument string 

EENDARGS 

DS 

F 


pointer to arg string end 

EFBLOCK 

DS 

F 


fileblock pointer (0) 

EARGLIST 

DS 

F 


pointer to function args 

EFUNRET 

DS • 

F 


location of return data 

*— DSECT for 

the returned 

data 

block-- 

EVALBLOK 

DSECT 
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EVBPADl 

DS 

F 

Reserved 

EVSIZE 

DS 

F 

Total block size in DW's 

EVLEN 

DS 

F 

Length of Data (in bytes) 

EVBPAD2 

DS 

F 

Reserved 

EVCTLEN 

EQU 

*-EVALBLOK 

Length of preceding section 

EVDATA 

DS 

OD 

First byte of data 

EVDATAWl 

DS 

F 

First word of data 

EVDATAW2 

DS 

F 

Second word of data 

EVDATAW3 

DS 

F 

Third word of data 

EVDATAW4 

DS 

F 

Fourth word of data 

EVDATAW5 

DS 

F 

Fifth word of data 


SPACE 

3 


* _nc-prfp 

m r tt? v t> r-» i <-+- 


uoiiiUi ior 

IN U L. H A 1 p IIS L 


DNUCX 

DSECT 

Overlayed by register 13 

DNLIST 

DS 

CL8 'NUCEXT' 

Name 

DNLNAME 

DS 

CL8 1 RXUSERFN' 

Function name 

DNLMASK 

DS 

X '00' 

Mask 

DNLKEY 

DS 

X '04' SYSTEM for 

RXUSERFN Key (04 - system. 

* 



E4 - user) 

DNLFLAG 

DS 

AL1 (SYSTEM) 

NUCEXT Flag 


DS 

X *00’ 

Spare flags 

DNLADDR 

DS 

A 

Entry point address 

•* 



(CANCEL = 0) 


DS 

AL4 (*-*) 

private 

DLSTART 

DS 

A 

Start address 

DLNLLEN 

DS 

AL4 (FREELEN) 

Length 


SPACE 

3 


*— DSECT for 

input parameters 

— 

PARMBLOK 

DSECT 



PARM1ADR 

DS 

F 

Address of parameter 1 

PARM1LEN 

DS 

F 

Length of parameter 1 

PARMNTRY 

EQU 

*-PARMBLOK 

Length of table entry 

PARM2ADR 

DS 

F 

Address of parameter 2 

PARM2LEN 

DS 

F 

Length of parameter 2 

PARM3ADR 

DS 

F 

Address of parameter 3 

PARM3LEN 

DS 

F 

Length of parameter 3 

PARM4ADR 

DS 

F 

Address of parameter 4 

PARM4LEN 

DS 

F 

Length of parameter 4 

PARM5ADR 

DS 

F 

Address of parameter 5 

PARM5LEN 

DS 

F 

Length of parameter 5 

PADR 

EQU 

0 , 4 

Offset in each pair to 

* 



parameter's address. 

PLEN 

EQU 

4,4 

Offset in each pair to 

* 



parameter * s length. 


SPACE 

3 



NUCON 




END 
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Appendix C. Error Numbers and Messages 


The error numbers produced by syntax errors during interpretation of 
REXX programs are all in the range 3-49 (and this is the value placed in the 
variable RC when SIGNAL ON SYNTAX event is trapped). The interpreter 
adds 20000 to these error return codes before leaving an EXEC in order to 
provide a different range of codes than those used by CMS EXEC and 
EXEC 2. When the interpreter displays an error message, it first sets the 
CMSTYPE indicator to ‘RT’, ensuring that the message will be seen by the 
user, even if ‘HT was in effect when the error occurred. 

Three of the error messages may be generated by the external interfaces to 
the interpreter either before the interpreter gains control, or after control 
has left the interpreter. Therefore these errors cannot be trapped by 
SIGNAL ON SYNTAX. The error numbers involved are: 3 and 5 (if the 
initial requirements for storage could not be met) and 26 (if on exit the 
returned string could not be converted to form a valid return code). 

Similarly, Error 4 can be trapped only by SIGNAL ON HALT. 

The CP command SET EMSG ON causes error messages to be prefixed with 
a CMS error code. The full form of the message, including this error code, 
is given below. Each message is followed by an explanation giving possible 
causes for the error. The same explanation can be obtained from CMS 
using the following command: 

HELP MSG DMSnnnE (where nnn is the CMS error number and error 
type is either *E* or'T’) 

In addition to the following error messages, the System Product Interpreter 
issues this terminal(unrecoverable) message: 

DMSREX255T Insufficient storage for Exec interpreter 

Explanation: There is insufficient storage for the System Product 
Interpreter to initialize itself. 

System Action: Execution is terminated at the point of the error. 

User Response: Redefine storage and reissue the command. 
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DMSREX449E Error 22 running fn ft, line nn: Invalid character 
string 

Explanation: A character string that has unmatched SO-SI pairs (that is, 
an SO without an SI) or an odd number of bytes between the SO-SI 
characters was scanned with OPTIONS ETMODE in effect. 

System Action: Execution stops. 

User Response: Correct the invalid character string in the EXEC file. 


DMSREX450E Error 5 running fn ft, line nn: Machine storage 
exhausted 

Explanation: While attempting to interpret a program, the System Product 
Interpreter was unable to get the space needed for its work areas and 
variables. This may have occurred because the program (such as the 
Editor) that invoked the System Product Interpreter has already used up 
most of the available storage itself, or because a program that issued 
NUCXLOAD did not terminate properly, but instead, went into a loop. 

System Action: Execution stops. 

User Response: Run the EXEC or macro on its own, or check a program 
issuing NUCXLOAD for a possible loop that has not terminated properly. 
More free storage may be obtained by releasing a disk (to recover the space 
used for the file directory) or deleting a nucleus extension. Alternatively, 
re-IPL CMS after defining a larger virtual storage size for the virtual 
machine. 


DMSREX451E Error 3 running fn ft, line nn Program is unreadable 

Explanation: The REXX program could not be read from the disk. This 
problem almost always occurs only when you are attempting to execute an 
EXEC or program from someone's disk for which you have Read/Only 
access, while someone with Read/Write access to the disk has altered the 
program so that it no longer exists in the same place on the disk. 

System Action: Execution stops. 

User Response: Reaccess the disk on which the EXEC or program resides. 
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DMSREX452E Error 4 running fn ft, line nn : Program interrupted 

Explanation: The system interrupted execution of your REXX program. 
Usually this is due to your issuing the HI (halt interpretation) immediate 
command. Certain utility modules may force this condition if they detect a 
disastrous error condition. 

System Action: Execution stops. 

User Response: If you issued an HI command, continue as planned. 
Otherwise, look for a problem with a Utility Module called in your EXEC 
or macro. 


DMSREX453E Error 6 running fn ft, line nn: Unmatched or quote 

Explanation: The System Product Interpreter reached the end of the file 
(or the end of data in an INTERPRET statement) without finding the 
ending "*l" for a comment or quote for a literal string. 

System Action: Execution stops. 

User Response: Edit the EXEC and add the closing "*/" or quote. You can 
also insert a TRACE SCAN statement at the top of your program and rerun 
it. The resulting output should show where the error exists. 


DMSREX454E Error 7 running fn ft, line nn: WHEN or OTHERWISE 
expected 

Explanation: The System Product Interpreter expects a series of WHENs 
and an OTHERWISE within a SELECT statement. This message is issued 
when any other instruction is found. This situation is often caused by 
forgetting the DO and END instructions around the list of instructions 
following a WHEN. For example, 

WRONG RIGHT 

Select Select 

When a=b then When a=b then DO 

Say 'A equals B' Say 'A equals B 1 

exit exit 

Otherwise nop end 

end Otherwise nop 

end 


System Action: Execution stops. 

User Response: Make the necessary corrections. 
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DMSREX455E Error 8 running fn ft, line nn : Unexpected THEN or 
ELSE 

Explanation: The System Product Interpreter has found a THEN or an 
ELSE that does not match a corresponding IF clause. This situation is 
often caused by forgetting to put an END or DO END in the THEN part of 
a complex IF THEN ELSE construction. For example, 

WRONG RIGHT 


If a=b then do; 
Say EQUALS 
exit 
else 

Say NOT EQUALS 


If a=b then do; 
Say EQUALS 
exit 
end 
else 

Say NOT EQUALS 


System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX456E Error 9 running fn ft, line nn: Unexpected WHEN or 
OTHERWISE 

Explanation: The System Product Interpreter has found a WHEN or 
OTHERWISE instruction outside of a SELECT construction. You may 
have accidentally enclosed the instruction in a DO END construction by 
leaving off an END instruction, or you may have tried to branch to it with 
a SIGNAL statement (which cannot work because the SELECT is then 
terminated). 

System Action: Execution stops. 

User Response: Make the necessary correction. 


DMSREX457E Error 10 running fn ft, line nn: Unexpected or 
unmatched END 

Explanation: The System Product Interpreter has found more ENDs in 
your program than DOs or SELECTs, or the ENDs were placed so that they 
did not match the DOs or SELECTs. 

This message can be caused if you try to signal into the middle of a loop. 

In this case, the END will be unexpected because the previous DO will not 
have been executed. Remember also, that SIGNAL terminates any current 
loops, so it can not be used to jump from one place inside a loop to another. 

This message can also be caused if you place an END immediately after a 
THEN OR ELSE construction. 
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System Action: Execution stops. 

User Response: Make the necessary corrections. It may be helpful to use 
“TRACE Scan” to show the structure of the program and make it more 
obvious where the error is. Putting the name of the control variable on 
ENDs that close repetitive loops can also help locate this kind of error. 


DMSREX458E Error 11 running fn ft, line nn: Control stack full 

Explanation: This message is issued if you exceed the limit of 250 levels of 
nesting of control structures (DO-END, IF-THEN-ELSE, etc.). 

This message could be caused by a looping INTERPRET instruction, such 

as: 

line=’INTERPRET line' 

INTERPRET line 

These lines would loop until they exceeded the nesting level limit and this 
message would be issued. Similarly, a recursive subroutine that does not 
terminate correctly could loop until it causes this message. 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX459E Error 12 running fn ft, line nn: Clause > 500 characters 

Explanation: You have exceeded the limit of 500 characters for the length 
of the internal representation of a clause. 

If the cause of this message is not obvious to you, it may be due to a 
missing quote, that has caused a number of lines to be included in one long 
string. In this case, the error probably occurred at the start of the data 
included in the clause traceback (flagged by + + + on the console). 

The internal representation of a clause does not include comments or 
multiple blanks that are outside of strings. Note also that any symbol 
(name) gains two characters in length in the internal representation. 

System Action: Execution stops. 

User Response: Make the necessary corrections. 
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DMSREX460E Error 13 running fn ft, line nn: 

Invalid character in data 

Explanation: The System Product Interpreter found an invalid character 
outside of a literal (quoted) string. Valid characters are: 

A-Z a-z 0-9 (Alphamerics) 

@ # $ C . ? i _ (Name Characters) 

&*()- + = -,»•' ;•<,.>/ (Special Characters) 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX461E Error 14 running fn ft , line nn: Incomplete 
DO/SELECT/IF 

Explanation: The System Product Interpreter has reached the end of the 
file (or end of data for an INTERPRET instruction) and has found that 
there is a DO or SELECT without a matching END, or an IF that is not 
followed by a THEN clause. 

System Action: Execution stops. 

User Response: Make the necessary corrections. You can use “TRACE 
Scan” to show the structure of the program, thereby making it easier to 
find where the missing END should be. Putting the name of the control 
variable on ENDs that close repetitive loops can also help locate this kind 
of error. 


DMSREX462E Error 15 running fn ft, line nn: 

Invalid hex constant 

Explanation: For the System Product Interpreter, hexadecimal constants 
may not have leading or trailing blanks and may have imbedded blanks at 
byte boundaries only. The following are all valid hexadecimal constants: 

* 13 1 x 

1 A3C2 lc34 1 x 

'laeQ'x 

You may have mistyped one of the digits, for example typing a letter o 
instead of a 0. This message can also be caused if you follow a string by the 
1-character symbol X (the name of the variable X ), when the string is not 
intended to be taken as a hexadecimal specification. In this case, use the 
explicit concatenation operator (||) to concatenate the string to the value of 
the symbol. 
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System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX463E Error 16 running fn ft, line nn: Label not found 

Explanation: The System Product Interpreter could not find the label 
specified by a SIGNAL instruction or a label matching an enabled condition 
when the corresponding (trapped) event occurred. You may have mistyped 
the label or forgotten to include it. 

System Action: Execution stops. The name of the missing label is 
included in the error traceback. 

User Response: Make the necessary corrections. 


DMSREX464E Error 21 running fn ft, line nn: Invalid data on end of 
clause 

Explanation: You have followed a clause, such as SELECT or NOP, by 
some data other than a comment. 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX465E Error 17 running fn ft, line nn: Unexpected 
PROCEDURE 

Explanation: The System Product Interpreter encountered a 
PROCEDURE instruction in an invalid position, either because no internal 
routines are active, or because a PROCEDURE instruction has already 
been encountered in the internal routine. This error can be caused by 
“dropping through” to an internal routine, rather than invoking it with a 
CALL or a function call. 

System Action: Execution stops. 

User Response: Make the necessary corrections. 
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DMSREX466E Error 26 running fn ft, line nn: 

Invalid whole number 

Explanation: The System Product Interpreter found an expression in the 
NUMERIC instruction, a parsing positional pattern, or the right hand term 
of the exponentiation (**) operator that did not evaluate to a whole number, 
or was greater than the limit, for these uses, of 999999999. 

This message can also be issued if the return code passed back from an 
EXIT or RETURN instruction (when a REXX program is called as a 
command) is not a whole number or will not fit in a System/370 register. 
This error may be due to mistyping the name of a symbol so that is is not 
the name of a variable in the expression on any of these statements. This 
might be true, for example, if you entered “EXIT CR” instead of “EXIT RC.” 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX467E Error 27 running fn ft, line nn: Invalid DO syntax 

Explanation: The System Product Interpreter found a syntax error in the 
DO instruction. You might have used BY or TO twice, or used BY, TO, or 
FOR when you didn't specify a control variable. 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX468E Error 30 running fn ft, line nn: Name or string > 250 
characters 

Explanation: The System Product Interpreter found a variable or a literal 
(quoted) string that is longer than the limit. 

The limit for names is 250 characters, following any substitutions. A 
possible cause of this error is the use of a period (.) in a name, causing an 
unexpected substitution. 

The limit for a literal string is 250 characters. This error can be caused by 
leaving off an ending quote (or putting a single quote in a string) because 
several clauses may be included in the string. For example, the string 
1 don * t 1 should be written as * don * * t 1 or " don ’ t " . 

System Action: Execution stops. 

User Response: Make the necessary corrections. 
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DMSREX469E Error 31 running fn ft, line nn : Name starts with 
numeric or 

Explanation: The System Product Interpreter found a variable whose 
name begins with a numeric digit or a period (.). The REXX language rules 
do not allow not allow you to assign a value to a variable whose name 
begins with a numeric digit or a period, because you could then redefine 
numeric constants which would be catastrophic. 

System Action: Execution stops. 

User Response: Rename the variable correctly. It is best to start a 
variable name with an alphabetic character, but some other characters are 
allowed. 


DMSREX470E Error 34 running fn ft, line nn: Logical value not 0 or 1 

Explanation: The System Product Interpreter found an expression in an 
IF, WHEN, DO WHILE, or DO UNTIL phrase that did not result in a 0 or 
1. Any value operated on by a logical operator (~i, |, &, or &&) must result 
in a 0 or 1. For example, the phrase “If result then exit rc” will fail if 
Result has a value other than 0 or 1. Thus, the phrase would be better 
written as If result~i=0 then exit rc . 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX471E Error 35 running fn ft, line nn: Invalid expression 

Explanation: The System Product Interpreter found a grammatical error 
in an expression. You might have ended an expression with an operator, or 
had two adjacent operators with no data in between, or included special 
characters (such as operators) in an intended character expression without 
enclosing them in quotes. For example LISTFILE * * * should be written as 
LISTFILE * * * * * (if LISTFILE is not a variable) or even as * LISTFILE 
* * * * 

System Action: Execution stops. 

User Response: Make the necessary corrections. 
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DMSREX472E Error 36 running fn ft , line nn: 

Unmatched in expression 

Explanation: The System Product Interpreter found an unmatched 
parenthesis within an expression. You will get this message if you include 
a single parenthesis in a command without enclosing it in quotes. For 
example, COPY A B C A B D (REP should be written as COPY A B C A B 
D * ( 1 REP. 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX473E Error 37 running fn ft y line nn: Unexpected or *)* 

Explanation: The System Product Interpreter found a comma (,) outside a 
routine invocation or too many right parentheses in an expression. You 
will get this message if you include a comma in a character expression 
without enclosing it in quotes. For example, the instruction: 

Say Enter A, B, or C 

should be written as: 

Say ’Enter A, B, or C 1 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX474E Error 39 running fn ft y line nn: Evaluation stack 
overflow 

Explanation: The System Product Interpreter was not able to evaluate the 
expression because it is too complex (many nested parentheses, functions, 
etc.). 

System Action: Execution stops. 

User Response: Break up the expressions by assigning sub-expressions to 
temporary variables. 
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DMSREX475E Error 40 running fn ft, line nn : Incorrect call to routine 

Explanation: The System Product Interpreter encountered an incorrectly 
used call to a built-in or external routine. Some possible causes are: 

• you passed invalid data (arguments) to the routine. This is the most 
common possible cause and is dependent on the actual routine. If a 
routine returns a non-zero return code, the System Product Interpreter 
issues this message and passes back its return code of 20040. 

• the module invoked was not compatible with the System Product 
Interpreter. 

If you were not trying to invoke a routine, you may have a symbol or a 
string adjacent to a “(” when you meant it to be separated by a space or an 
operator. This causes it to be seen as a function call. For example, 

TIME(4 + 5) should probably be written as TIME* (4+5). 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX476E Error 41 running fn ft, line nn: Bad arithmetic 
conversion 

Explanation: The System Product Interpreter found a term in an 
arithmetic expression that was not a valid number or that had an exponent 
outside the allowed range of -999999999 to + 999999999. 

You may have mistyped a variable name, or included an arithmetic operator 
in a character expression without putting it in quotes. For example, the 
command MSG * Hi! should be written as 'MSG * Hi! ', otherwise the 
System Product Interpreter will try to multiply “MSG” by “Hi!.” 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX477E Error 42 running fn ft, line nn: Arithmetic 
overflow/underflow 

Explanation: The System Product Interpreter encountered the result of an 
arithmetic operation that required an exponent greater than the limit of 9 
digits (more than 999999999 or less than -999999999). 

This error can occur during evaluation of an expression (often as a result of 
trying to divide a number by 0), or during the stepping of a DO loop control 
variable. 
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System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX478E Error 43 running fn ft 9 line nn: Routine not found 

Explanation: The System Product Interpreter was unable to find a routine 
called in your program. You invoked a function within an expression, or in 
a subroutine invoked by CALL, but the specified label is not in the 
program, or is not the name of a built-in function, and CMS is unable to 
locate it externally. 

The simplest, and probably most common, cause of this error is mistyping 
the name. Another possibility may be that one of the standard function 
packages is not available. 

If you were not trying to invoke a routine, you may have put a symbol or 
string adjacent to a “(” when you meant it to be separated by a space or 
operator. The System Product Interpreter would see that as a function 
invocation. For example, the string 3(4 + 5) should be written as 3* (4+5). 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX479E Error 44 running fn ft 9 line nn: Function did not return 
data 

Explanation: The System Product Interpreter invoked an external routine 
within an expression. The routine seemed to end without error, but it did 
not return data for use in the expression. 

This may be due to specifying the name of a CMS module that is not 
intended for use as a System Product Interpreter function. It should be 
called as a command or subroutine. 

System Action: Execution stops. 

User Response: Make the necessary corrections. 
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DMSREX480E Error 45 running fn ft, line nn: No data specified on 
function RETURN 

Explanation: A REXX program has been called as a function, but an 
attempt is being made to return (by a RETURN; instruction) without 
passing back any data. Similarly, an internal routine, called as a function, 
must end with a RETURN statement specifying an expression. 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX481E Error 49 running fn ft, line nn : Interpreter failure 

Explanation: The System Product Interpreter carries out numerous 
internal self-consistency checks. It issues this message if it encounters a 
severe error. 

System Action: Execution stops. 

User Response: Report any occurrence of this message to your IBM 
representative. 


DMSREX482E Error 19 running fn ft, line nn: String or symbol 
expected 

Explanation: The System Product Interpreter expected a symbol following 
the keywords CALL, SIGNAL, SIGNAL ON, or SIGNAL OFF but none was 
found. You may have omitted the string or symbol, or you may have 
inserted a special character (such as a parenthesis) in it. 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX483E Error 20 running fn ft, line nn: Symbol expected 

Explanation: The System Product Interpreter may expect a symbol 
following the END, ITERATE, LEAVE, NUMERIC, PARSE, or 
PROCEDURE keywords or expected a list of symbols following the DROP, 
UPPER, or PROCEDURE (with EXPOSE option) keywords. Either there 
was no symbol when one was required or some other characters were found. 

System Action: Execution stops. 
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User Response: Make the necessary corrections. 


DMSREX484E Error 24 running fn ft, line nn: Invalid TRACE request 

Explanation: The System Product Interpreter issues this message when: 

• the action specified on a TRACE instruction, or the argument to the 
built-in function, starts with a letter that does not match one valid 
alphabetic character options. The valid options are A, C, E, I, L, N, O, 
R, or S. 

• an attempt is made to request “TRACE Scan” when inside any control 
construction or while in interactive debug. 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX485E Error 25 running fn ft, line nn: Invalid sub-keyword 
found 

Explanation: The System Product Interpreter expected a particular 
sub-keyword at this position in an instruction and something else was 
found. For example, the NUMERIC instruction must be followed by the 
sub-keyword DIGITS, FUZZ, or FORM. If NUMERIC is followed by 
anything else, this message is issued. 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX486E Error 28 running fn ft, line nn: Invalid LEAVE or 
ITERATE 

Explanation: The System Product Interpreter encountered an invalid 
LEAVE or ITERATE instruction. The instruction was invalid because: 

• no loop is active, or 

• the name specified on the instruction does not match the control 
variable of any active loop. 

Note that internal routine calls and the INTERPRET instruction protect 
DO loops by making them inactive. Therefore, for example, a LEAVE 
instruction in a subroutine cannot affect a DO loop in the calling routine. 
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You can cause this message to be issued if you use the SIGNAL instruction 
to transfer control within or into a loop. A SIGNAL instruction terminates 
all active loops, and any ITERATE or LEAVE instruction issued then 
would cause this message to be issued. 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX487E Error 29 running fn ft, line nn: Environment name too 
long 

Explanation: The System Product Interpreter encountered an environment 
name specified on an ADDRESS instruction that is longer than the limit of 
8 characters. 

System Action: Execution stops. 

User Response: Specify the environment name correctly. 


DMSREX488E Error 33 running fn ft, line nn: Invalid expression 
result 

Explanation: The System Product Interpreter encountered an expression 
result that is invalid in its particular context. The result may be invalid 
because an illegal FUZZ or DIGITS value was used in a NUMERIC 
instruction (FUZZ may not become larger that DIGITS). 

System Action: Execution stops. 

User Response: Make the necessary corrections. 


DMSREX489E Error 38 running fn ft, line nn: Invalid template or 
pattern 

Explanation: The System Product Interpreter found an invalid special 
character, for example %, within a parsing template, or the syntax of a 
variable trigger was incorrect (no symbol was found after a left 
parenthesis). This message is also issued if the WITH sub-keyword is 
omitted in a PARSE VALUE instruction. 

System Action: Execution stops. 

User Response: Make the necessary corrections. 
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DMSREX490E Error 48 running fn ft , line nn: Failure in system 
service 

Explanation: The System Product Interpreter halts execution of the 
program because some system service, such as user input or output or 
manipulation of the console stack has failed to work correctly. 

System Action: Execution stops. 

User Response: Ensure that your input is correct and that your program 
is working correctly. If the problem persists, notify your system support 
personnel. 


DMSREX491E Error 18 running fn ft, line nn : THEN expected 

Explanation: All REXX IF and WHEN clauses must be followed by a 
THEN clause. Another clause was found before a THEN statement was 
found. 

System Action: Execution stops. 

User Response: Insert a THEN clause between the IF or WHEN clause 
and the following clause. 


DMSREX492E Error 32 running fn ft, line nn: Invalid use of stem 

Explanation: The REXX program attempted to change the value of a 
symbol that is a stem. (A stem is that part of a symbol up to the first 
period. You use a stem when you want to affect all variables beginning 
with that stem.) This may be in the UPPER instruction where the action in 
this case is unknown, and therefore in error. 

System Action: Execution stops. 

User Response: Change the program so that it does not attempt to change 
the value of a stem. 
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Appendix D. The System Product Interpreter in the GCS 

Environment 


Most REXX capabilities available in the CMS environment are also 
available in the GCS environment. You can use the REXX instructions, 
functions, expressions, operators, etc. There are, however, some differences 
between writing REXX programs for the GCS environment and writing 
REXX programs for the CMS environment. 

The differences in the GCS environment are as follows: 

1. EXECs normally reside in CMS formatted disk files and have a filetype 
of GCS. The GCS filetype can be overridden by using the FILEBLK. 

2. GCS does not support the following immediate commands: TS, TE, and 
HI. 

3. An EXEC written for the GCS environment should not have the same 
name as an immediate command. Immediate commands are higher in 
the search order, therefore, an immediate command would be executed 
before an EXEC. An EXEC written for the GCS environment with the 
same name as an immediate command would never get executed. 

4. GCS does not support the external function libraries: RXSYSFN, 
RXLOCFN, and RXUSERFN. However, GCS does support external 
function calls. These functions and subroutines must be written in the 
REXX language. 

5. The GCS CMDSI macro can be used to invoke REXX programs from 
Assembler language programs. The FILEBLK parameter on the CMDSI 
macro contains the address of the file block. FILEBLK is useful for 
executing in-storage EXECs, executing EXECs with filetypes other than 
GCS, and establishing an initial subcommand environment. 

6. The default ADDRESS environment of REXX is GCS. 

ADDRESS GCS specifies that full command resolution is in effect. 

With full command resolution, first search for an EXEC with the given 
name. If such an EXEC does not exist, then invoke the given name 
using SVC 202. If the above fails, search for a CP command with the 
given name. 

ADDRESS COMMAND searches for host commands (GCS commands). 

7. GCS does not have a terminal input buffer. If you issue a PULL 
instruction and the program stack is empty, the WTOR macro generates 
a read to the console. 
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8. Each task has its own program stack. Therefore, data in a program 
stack can be shared among EXECs running in the same task. 

9. To specify other subcommand environments in GCS you must use 
LOADCMD. LOADCMD defines a command name to the requested 
module of a CMS load library and loads this command module into 
storage. Therefore, GCS can call the requested command module when 
a command is entered at the console or submitted by a program with the 
CMDSI macro. 

GCS does not support non-SVC fast path subcommand invocation. 

10. The SIGNAL ON HALT instruction has no effect in GCS. 


Processing EXECs in GCS (CSIREX module) 

All EXEC processing in GCS is routed to the GCS module, CSIREX. 
CSIREX is the external interface for the System Product Interpreter 
(CSIRIN). 

SVC 202 calls CSIREX with the contents of the registers as follows: 

R0 Address of the extended parameter list 

R1 Address of the standard tokenized parameter list 

R12 Address of the entry point 

R13 Address of a register savearea 

R14 Return address 

R15 Address of the entry point (same as R12) 

The Extended Plist 


The extended plist has the 

following format: 

EPLIST 

DSECT 



EPLCMD 

DS 

A 

Address of command token 

EPLARGBG 

DS 

A 

Address of beginning of arguments 

EPLARGND 

* 

DS 

A 

Address of byte following the end 
of arguments 

EPFBL 

DS 

A 

Address of the file block 

EPARGLST 

* 

DS 

A 

Address of function argument list 
for EXEC 

EPFUNRET 

* 

DS 

A 

Address for return of function data 
for EXEC 
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EPLIND 

DS 

X 

EPLPGM 

EQU 

X'OO’ 

EPLACMD 

* 

EQU 

X'Ol* 

EPLFNC 

EQU 

x'os* 

EPLCONS 

EQU 

X 1 OB • 

EPLRESVD 

DS 

3X 


The Standard Tokenized Plist 


Indicator 

Program issued command 

Call from System Product Interpreter 

when ADDRESS COMMAND is specified 

Subroutine/function call 

Console command 

Reserved 


The standard tokenized plist has the following format: 


DC CL8 * EXEC' 

DC CL8'execname' 

DC XL8'FF 1 


The File Block 


The file block has the following format: 


FBLOCK 

DSECT 


FBLNAME 

DS 

CL8 

Program name (usually EXEC filename) 

FBLTYPE 

DS 

CL8 

Program type/default prefix 

* 



(usually GCS filetype) 

FBLMODE 

DS 

CL2 

Program filemode 

FBLEXTL 

DS 

H 

Extension block length in fullwords 

FBLEXT 

EQU 

* 

Extension block starts here 

* The i 

next 2 

words 

represent the start 

* and ( 

end of 

in-storage EXECs 

FBLDLS 

DS 

AL4 

Descriptor list starts here 

FBLDLE 

DS 

AL4 

Descriptor length 

FBLPREF 

DS 

CL8 

Explicit initial prefix 


EXECCOMM Processing (Sharing Variables) 

The EXECCOMM macro allows programs to access and manipulate the 
current generation of REXX variables. These variables may be inspected, 
set, or dropped. To use the EXECCOMM capability, a REXX program must 
be active on the current task. 

The format of the EXECCOMM macro is: 
flabel] EXECCOMM REQLIST=addr 

where: 

REQLIST is a RX-type address or register, addr specifies the address of 
the shared variable request block chain. Each caller is 
responsible for setting up their its variable request block chain. 

The internal REXX work areas are manipulated by the System Product 
Interpreter's own routines. Therefore, the user's program does not need to 
know the structure of the variable's access method. 
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The EXECCOMM macro generates an SVC 203, and the register input for 
EXECCOMM processing is as follows: 

R0 Shared variable request block chain pointer 

R12 Entry point address 

R13 Save area address 

R14 Return address 

R15 Entry point address 

On return from the SVC 203, register 15 contains the return codes. The 
possible return codes are: 

0 or positive Entire request list was processed 

-1 Invalid entry condition (no REXX program active on this 

task) 

-2 Insufficient storage available to process the request 

Shared Variable Request Block 

If the address of the shared variable request block passed in register 0 is 
invalid, the task is terminated with abend code FCB and reason code 0D01. 
Each request block in the chain must be structured as follows: 
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************************************************************ 


SHVBLOCK DSECT 

SHVNEXT DS A Chain pointer to next element or 0 

SHVUSER DS F Used during "Fetch Next" 

SHVCODE DS CL1 Individual function code 

SHVRET DS XL1 Individual return code flags 

DS H 1 0 * Not used 

SHVBUFL DS F Length of ’ Fetch* value buffer 

SHVNAMA DS A Address of variable name 

SHVNAML DS F Length of variable name 

SHVVALA DS A Address of value buffer 

SHVVALL DS F Length of value (set on ’Fetch 1 ) 

★ 

* Function Codes (SHVCODE): 

★ 

SHVSET EQU C’S’ Set variable from given value 
SHVFETCH EQU C’F’ Copy value of variable to buffer 

SHVDROPV EQU C’D* Drop variable 

SHVSYSET EQU C’s' Symbolic name Set variable 

SHVSYFET EQU C'f* Symbolic name Fetch variable 

SHVSYDRO EQU C'd* Symbolic name Drop variable 

SHVNEXTV EQU C'N' Fetch 'Next' variable 

SHVPRIV EQU C'P* Fetch private information 

* 

* Return Codes (SHVRET) 

* 

SHVCLEAN EQU X'OO' Execution was OK 

SHVNEWV EQU X'01' Variable did not exist 

SHVLVAR EQU X'02' Last variable transferred (for 'N') 

SHVTRUNC EQU X'04' Truncation occurred during 'Fetch' 

SHVBADN EQU X'08' Invalid variable name 

SHVBADV EQU X'10' Reserved in REXX 

SHVBADF EQU X'80' Invalid function code (SHVCODE) 
************************************************************ 

A typical calling sequence using the EXECCOMM macro is: 

EXECCOMM REQLIST=(5) 

where register 5 points to the first of a chain of one or more request blocks. 

Function codes (SHVCODE) 

Three function codes (S, F, and D) may be given either in lowercase or in 
uppercase: 

Lowercase (The symbolic interface). The names must be valid REXX 
symbols (in mixed case if desired), and normal REXX 
substitution will occur in compound variables. 

Uppercase (The direct interface). No substitution or case translation 
takes place. Simple symbols must be valid REXX variable 
names (that is, in uppercase, and not starting with a digit or a 
period). Compound symbols must contain a valid REXX stem. 
However, any characters are permitted (including lowercase, 
blanks, etc.) following this valid stem. 

Note: The direct interface should be used in preference to the symbolic 
interface whenever generality is desired. 
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The other function codes, N and P, must always be given in uppercase. The 

specific actions for each function code are as follows: 

S and s Set variable. The SHVNAMA/SHVNAML adlen describes the 
name of the variable to be set, and SHVVALA/SHVVALL 
describes the value that is to be assigned to it. The name is 
validated to ensure that it does not contain invalid characters. 

The variable is then set from the value given. If the name is a 
stem, all variables with that stem are set, just as though this were 
a REXX assignment. SHVNEWV is set if the variable did not 
exist before the operation. 

F and f Fetch variable. The SHVNAMA/SHVNAML adlen describes the 
name of the variable to be fetched. SHVVALA specifies the 
address of a buffer into which the data is to be copied, and 
SHVBUFL contains the length of the buffer. The name is 
validated to ensure that it does not contain invalid characters, 
and the variable is then located and copied to the buffer. The 
total length of the variable is put into SHVVALL, and, if the 
value was truncated (because the buffer was not big enough), the 
SHVTRUNC bit is set. If the variable is shorter than the length 
of the buffer, no padding takes place. If the name is a stem, the 
initial value of that stem (if any) is returned. 

SHVNEWV is set if the variable did not exist before the 
operation, and in this case the value copied to the buffer is the 
derived name of the variable (after substitution etc.). See page 13. 

D and d Drop variable. The SHVNAMA/SHVNAML adlen describes the 
name of the variable to be dropped. SHVVALA/SHVVALL are 
not used. The name is validated to ensure that it does not contain 
invalid characters, and the variable is then dropped, if it exists. If 
the name given is a stem, all variables starting with that stem are 
dropped. SHVNEWV is set if no variables were affected by the 
operation. 

N Fetch Next variable. This function may be used to search 

through all the variables known to the interpreter (that is, all 
those of the current generation, excluding those “hidden” by 
PROCEDURE instructions). The order in which the variables are 
revealed is not specified. 

The interpreter maintains a pointer to its list of variables: this is 
reset to point to the first variable in the list whenever 1) a host 
command is issued, or 2) any function other than “N” is executed 
via EXECCOMM. 

Whenever an N (Next) function is executed, the name and value 
of the next variable available are copied to two buffers supplied by 
the caller. 

SHVNAMA specifies the address of a buffer into which the name 
is to be copied, and SHVUSER contains the length of that buffer. 
The total length of the name is put into SHVNAML, and, if the 
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name was truncated (because the buffer was not big enough), the 
SHVTRUNC bit is set If the name is shorter than the length of 
the buffer, no padding takes place. The value of the variable is 
copied to the user's buffer area using exactly the same protocol as 
for the fetch operation. 

If SHVRET has SHVLVAR set, the end of the list of known 
variables has been found, the internal pointers have been reset, 
and no valid data has been copied to the user buffers. If 
SHVTRUNC is set, either the name or the value has been 
truncated. 

By repeatedly executing the N function (until the SHVLVAR flag 
is set), a user program can locate all the REXX variables of the 
current generation. 

Fetch private information. This function is identical to the F 
fetch function, except that the name refers to certain fixed 
information items that are available. Only the first letter of each 
name is checked (though callers should supply the whole name). 
The following names are recognized: 

ARG Fetch primary argument string. The first argument 
string that would be parsed by the ARG instruction is 
copied to the user's buffer. 

SOURCE Fetch source string. The source string, as described for 
PARSE SOURCE on page 47, is copied to the user's 
buffer. 

VERSION Fetch version string. The source string, as described 

for PARSE VERSION on page 48, is copied to the user's 
buffer. 
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Summary of Changes 


Summary of Changes 
for SC24-5239-2 
for VM/SP Release 5 

How to Obtain the Release 4 of this Publication 

To obtain the edition of this publication that pertains to Release 4 of VM/SP, 
order SQ24-5239 
New DATE Function option 
A new option, Basedate (B) has been added. 

New DIAG Function 

DIAG(C8), DIAGRC(C8), DIAG(CC) and DIAGR(CC) returns information related to 
CP language repository. 

Miscellaneous 

Minor technical and editorial changes have been made throughout this 
publication. 

Summary of Changes 
for SC24-5239-1 
for VM/SP Release 4 

GCS Environment 

A new appendix, Appendix D, has been added to describe REXX in the GCS 
environment. 

New OPTIONS Instruction 

The OPTIONS instruction specifies whether double byte character set (DBCS) 
strings can be manipulated. 

New DIAG Function 

DIAG(8C) and DIAGRC(8C) returns device-dependent information about the 
virtual console. 
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Miscellaneous 


Minor technical and editorial changes have been made throughout this 
publication. 
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Index 


Special Characters 


. (period) 

as placeholder in parsing 129 

causing substitution in variable names 13 

in numbers 135 

< (less than operator) 8 

< > (less than or greater than operator) 8 

< = (less than or equal operator) 8 
+ (addition operator) 7, 135 

+ + + tracing flag 66 
| (inclusive OR operator) 9 
|| (concatenation operator) 7 
& (AND operator) 9 
&& (exclusive OR operator) 9 
! prefix on TRACE instruction 64 
* (multiplication operator) 7, 135 
** (exponentiation operator) 7, 136 
*-* tracing flag 66 
(NOT operator) 9 
*“» < (not less than operator) 8 
“i > (not greater than operator) 8 
-> = (not equal operator) 8 

= = (not exactly equal operator) 8 
- (subtraction operator) 7, 135 
/ (division operator) 7, 135 
II (remainder operator) 7, 136 
/ - (not equal operator) 8 
/ “ = (not exactly equal operator) 8 
% (integer division operator) 7, 136 

> (greater than operator) 8 
>. > tracing flag 66 

> < (greater than or less than operator) 8 

> > > tracing flag 66 

> = (greater than or equal operator) 8 


>c> 

tracing flag 

66 

>F> 

tracing flag 

66 

>L> 

tracing flag 

66 

>0> 

tracing flag 

66 

>P> 

tracing flag 

66 

>V> 

tracing flag 

66 


? prefix on TRACE instruction 64 
= (equal sign) 

assignment indicator 12 
equal operator 8 
immediate debug command 117 
in DO instruction 31 
= = (exactly equal operator) 8 
"HT" flag 


cleared before error messages 177 


A 


ABBREV function 
description 73 
using to select a default 73 
abbreviations 

looking for one in a string 131 
testing with ABBREV function 73 
abnormal change in flow of control 58 
ABS function 74 
absolute value 

finding using ABS function 74 
used with exponentiation 136 
active loops 41 
addition 

definition 135 
operator 7 
ADDRESS 
function 74 
instruction 24 

settings saved during subroutine calls 29 
algebraic precedence 9 
alphabetics 

checking with DATATYPE 80 
used as symbols 3 

alphanumeric checking with DATATYPE 80 
altering 

flow within a repetitive DO loop 41 
REXX variables 16 
AND operator 9 
AND, logical 9 

AND'ing character strings together 76 

ARG function 75 

ARG instruction 26 

ARG option of PARSE instruction 46 

arguments 

checking with ARG function 75 
of EXECs 26 
of functions 26, 69 
of subroutines 26, 28 
passing to EXECs 153 
passing to functions 69 
retrieving with ARG function 75 
retrieving with ARG instruction 26 
retrieving with the PARSE ARG instruction 46 
arithmetic 

combination rules 137 
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comparisons 139 
errors 141 

NUMERIC settings 44 
operators 7,133, 135 
overflow 141 
precision 135 
underflow 141 
array 

initialization of 14 
setting up 13 

assigning data to variables 46 
assignment 

description of 12 
of compound variables 13, 14 
assignment indicator (=) 12 
associative storage 13 


B 


BASEDATE option of DATE function 81 

BITAND function 76 

BITOR function 76 

bits checked using DATATYPE 80 

BITXOR function 77 

blank removal with STRIP function 94 

blanks 

adjacent to special character 2 
as concatenation operator 7 
boolean operations 9 

bottom of program reached during execution 37 
built-in function invoking 28 
built-in functions 
ABBREV 73 
ABS 74 
ADDRESS 74 
ARG 75 
BITAND 76 
BITOR 76 
BITXOR 77 
CENTER 77 
CENTRE 77 
COMPARE 78 
COPIES 78 
C2D 78 
C2X 79 
DATATYPE 80 
DATE 81 
DELSTR 82 
DELWORD 82 
description of 70 
D2C 83 
D2X 84 

ERRORTEXT 84 
EXTERNALS 85 
FIND 85 
FORMAT 85 
INDEX 86 


INSERT 87 
JUSTIFY 87 
LASTPOS 88 
LEFT 88 
LENGTH 88 
LINESIZE 89 
MAX 89 
MIN 89 
OVERLAY 90 
POS 90 
QUEUED 91 
RANDOM 91 
REVERSE 92 
RIGHT 92 
SIGN 93 
SOURCELINE 93 
SPACE 93 
STRIP 94 
SUBSTR 94 
SUBWORD 95 
SYMBOL 95 
TIME 96 
TRACE 97 
TRANSLATE 98 
TRUNC 98 
USERID 99 
VALUE 99 
VERIFY 100 
WORD 100 
WORDINDEX 101 
WORDLENGTH 101 
WORDS 101 
XRANGE 102 
X2C 102 
X2D 102 

BY phrase of DO instruction 31 


c 

_ 

CALL instruction 28 
CENTER function 77 

centering a string using CENTER function 77 
centering a string using CENTRE function 77 
CENTRE function 77 
CENTURY option of DATE function 81 
changing destination of commands 24 
character position of a string 88 
character position using INDEX 86 
character removal with STRIP function 94 
character to decimal conversion 78 
character to hexadecimal conversion 79 
clause 

as labels 11 
assignment 11, 12 
continuation of 5 
description of 2 
null 11 
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CMS (Conversational Monitor System) 
COMMAND environment 20 
environment name 17, 25 
issuing commands to 16, 17, 24, 25 
search order 17 
unique functions 104 

CMS (Conversational Monitor System) commands 
EXECDROP 147 
EXECIO 147 
EXECLOAD 147 
EXECMAP 147 
EXECOS 147 
EXECSTAT 147 
EXECUPDT 147 
GLOBALV 147 
IDENTIFY 147 
LISTFILE 147 
PARSECMD 147 
QUERY 147 
SET 147 
XEDIT 147 
XMITMSG 147 
codes, error 177-192 
collating sequence using XRANGE 102 
colon as label terminators 11 
combination, arithmetic 137 
COMMAND as an environment name 20, 25 
command environments 
See environments 
command errors, trapping 
See SIGNAL instruction 
command inhibition 

See TRACE instruction 
commands 

alternative destinations 16 
destination of 24 

inhibiting with TRACE instruction 64 
issuing to host 16 
comments 

description of 2 

to identify program language 149 
COMPARE function 78 
comparisons 

of numbers 8, 139 
of strings 8 

using COMPARE 78 
compound variable 
description of 13 
setting new value 14 
concatenation of strings 7 
concatenation operator 
II 7 

blank 7 

conditional loops 31 
conditions 
ERROR 58 
HALT 58 
NOVALUE 58 

saved during subroutine calls 29 
SYNTAX 58 


conditions, trapping of 
See SIGNAL instruction 
console 

reading from with PULL 51 
writing to with SAY 55 
constant symbols 12 
content addressable storage 13 
continuation 
character 5 
of clauses 5 
of data for display 55 
Control Program (CP) 

issuing commands to 17 
control variable 33 
controlled loops 33 
Conversational Monitor System (CMS) 
COMMAND environment 20 
environment name 17, 25 
issuing commands to 16, 17, 24 
search order 17 
unique functions 104 
conversion 

character to decimal 78 
character to hexadecimal 79 
decimal to character 83 
decimal to hexadecimal 84 
formatting numbers 85 
hexadecimal to character 102 
hexadecimal to decimal 102 
conversion functions 73-103 
COPIES function 78 
copying a string using COPIES 78 
counting words in a string 101 
CP (Control Program) 

issuing commands to 17 
current terminal line width 89 
C2D function 78 
C2X function 79 


D 


data length 6 

data terms 6 

DATATYPE function 80 

date and version of the interpreter 48 

DATE function 81 

DBCS (Double-Byte Character Set) strings 45 
debug, interactive 62, 117 
debugging programs 

See interactive debug 
See TRACE instruction 
decimal arithmetic 133-142 
decimal to character conversion 83 
decimal to hexidecimal conversion 84 
default environment 16 
deleting part of a string 82 
deleting words from a string 82 
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delimiters in a clause 
See? 

See semicolons 
DELSTR function 82 
DELWORD function 82 
derived name 13 
derived names of variables 13 
DIAG function 105 
DIAGRC function 106 

DIGITS option of NUMERIC instruction 44, 135 
direct interface to variables 159 
displaying data 

See SAY (REXX instruction) 
division 

definition 135 
operator 7 
DO instruction 31, 35 
See also loops 

Double-Byte Character Set (DBCS) strings 45 
DROP instruction 36 
dummy instruction 

See NOP instruction 
D2C function 83 
D2X function 84 


E 


editor macros 24 

elapsed time calculator 96 

elapsed time saved during subroutine calls 29 

ELSE keyword 

See IF instruction 
END clause 

See also DO instruction 
See also SELECT instruction 
specifying control variable 33 
engineering notation 141 
environments 

addressing of 24 
default 25, 47, 153 
determining current using ADDRESS 
function 74 
temporary change of 24 
equal operator (=) 8 
equality, testing of 8 
error codes 177-192 

ERROR condition of SIGNAL instruction 58 
error messages 

retrieving with ERRORTEXT 84 
error messages and codes 177-192 
errors 

during execution of functions 73 
from host commands 16 


syntax 177-192 
traceback after 66 
errors, trapping 

See SIGNAL instruction 
ERRORTEXT function 84 
EUROPEAN option of DATE function 81 
EVALBLOK format 155 
evaluation of expressions 6 
exactly equal operator (= =) 8 
exception conditions saved during subroutine 
calls 29 

exclusive OR operator 9 

exclusive ORing character strings together 77 

EXECCOMM 

interface to variables 159 
subcommand entry point 159 
EXECFLAG byte in NUCON 164 
EXECs 

arguments to 26 
calling as functions 70, 157 
in-store execution of 153 
invoking 149 
plist for 149 
retrieving name of 47 
EXECTRAC flag 

external control of tracing 120 
execution by interpreter 1 
execution of data 39 
EXIT instruction 37 
exponential notation 
definition 140 
description of 133 
usage 4 
exponentiation 
definition 136 
operator 7 

EXPOSE option of PROCEDURE instruction 49 
expressions 

evaluation 6 
examples 10 
parsing of 48 
results of 6 
tracing results of 62 
extended plist 153 
external functions 
description of 70 
interface 157 

EXTERNAL option of PARSE instruction 46 
external routine invoking 28 
external subroutines 
interface 157 
external trace bit 120 
in EXECFLAG 164 
EXTERNALS function 85 
extracting a substring 94 
extracting words from a string 95 
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F 


FIFO (first-in/first-out) stacking 53 
file name, type, mode of program 47 
FIND function 85 

finding a mismatch using COMPARE 78 
finding a string in another string 86, 90 
finding the length of a string 88 
flow control 

abnormal, with SIGNAL 58 
with CALL/RETURN 28 
with DO construct 31 
with IF construct 38 
with SELECT construct 56 
FOR phrase of DO instruction 31 
FOREVER repetitor on DO instruction 31 
FORM option of NUMERIC instruction 44, 141 
FORMAT function 85 
formatting 

numbers for display 85 
numbers with TRUNC 98 
of output during tracing 66 
text centering 77 
text justification 87 
text left justification 88 
text right justification 92 
text spacing 93 
function, built-in 

See built-in functions 
functions 

built-in 70, 73 
calling EXECs as 157 
description of 69 
external 70 
external interface 157 
external packages 103-116 
for VM/SP information 104 
forcing built-in or external reference 71 
internal 70 
invocation of 69, 153 
numeric arguments of 141 
return from 54 
variables in 49 
FUZZ 

controlling numeric comparison 139 
option of NUMERIC instruction 44, 139 


G 


GCS (Group Control System) environment 193 
GOTO, abnormal 

See SIGNAL instruction 
greater than operator (>) 8 
greater than or equal operator (> =) 8 
greater than or less than operator (> <) 8 


Group Control System (GCS) environment 193 
group, DO 32 

grouping instructions to execute repetitively 31 


H 


HALT condition of SIGNAL instruction 58 
Halt Interpretation (HI) immediate command 117 
halt, trapping 

See SIGNAL instruction 
halting a looping program 119 
hexadecimal 

See also conversion 
checking with DATATYPE 80 
hexadecimal strings 3 

HI (Halt Interpretation) immediate command 119 

host commands 16 

hours calculated from midnight 96 


0 

identifying users 99 
IF instruction 38 
immediate commands 

HI (Halt Interpretation) 119 
TE (Trace End) 119 
TS (Trace Start) 119 
implementation details 167 
implied semicolons 5 
imprecise numeric comparison 139 
in-store execution of EXECs 153 
inclusive OR operator 9 
indefinite loops 31 

See also looping program 
indentation during tracing 66 
INDEX function 86 
indirect evaluation of data 39 
inequality, testing of 8 
infinite loops 31 

See also looping program 
inhibition of commands with TRACE 
instruction 64 
initialization 
of arrays 14 

of compound variables 14 
INSERT function 87 
inserting a string into another 87 
instructions 

ADDRESS 24 
ARG 26 
CALL 28 
DO 31 
DROP 36 
EXIT 37 
IF 38 
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INTERPRET 39 
ITERATE 41 
LEAVE 42 
NOP 43 
NUMERIC 44 
OPTIONS 45 
PARSE 46 
PROCEDURE 49 
PULL 51 
PUSH 52 
QUEUE 53 
RETURN 54 
SAY 55 
SELECT 56 
SIGNAL 58 
TRACE 62 
UPPER 68 

integer arithmetic 133-142 
integer division 
definition 136 
description of 133 
operator 7 

interactive debug 62, 117 

See also TRACE instruction 
interfaces 

system 149 

to external routines 157 
to variables 159 
internal functions 
description of 70 
return from 54 
variables in 49 
internal routine invoking 28 
INTERPRET instruction 39 
interpreter date and version 48 
interpretive execution of data 39 
interrupting program execution 119 
invoking 

built-in functions 28 
routines 28 
ITERATE instruction 

See also DO instruction 

description 41 

use of variable on 41 


0 

JULIAN option of DATE function 81 
JUSTIFY function 87 
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keywords 

See also instructions 
conflict with commands 143 
mixed case 23 
reservation of 143 


0 

label 

as targets of CALL 28 
as targets of SIGNAL 58 
description of 11 
duplicate 58 

in INTERPRET instruction 39 
search algorithm 58 
language structure and syntax 2 
LASTPOS function 88 

leading blank removal with STRIP function 94 
leading zeros 

adding with the RIGHT function 92 
removal with STRIP function 94 
LEAVE instruction 

See also DO instruction 
description of 42 
use of variable on 42 
leaving your program 37 
LEFT function 88 
LENGTH function 88 
less than operator ( <) 8 
less than or equal operator ( < =) 8 
less than or greater than operator ( < >) 8 
LIFO (last-in/first-out) stacking 52 
line length of terminal 89 
line width of terminal 89 
lines from a program retrieved with 
SOURCELINE 93 
LINESIZE function 89 
list 13 

locating a phrase in a string 85 
locating a string in another string 86, 90 
logical bit operations 
BITAND 76 
BITOR 76 
BITXOR 77 
logical operations 9 
lookaside buffering 167 
looping program 
halting 119 
tracing 119 
loops 

See also DO instruction 
See also looping program 
active 41 






execution model 35 
modification of 41 
repetitive 31 
termination of 42 
lower case symbols 3 


M 


macros, editor 

24 

MAX function 

89 

memory 


accessing 

116 


finding upper limit of 116 
messages, error 177-192 
MIN function 89 

minutes calculated from midnight 96 
MONTH option of DATE function 81 
multiple 

argument passing 153 
string parsing 131 
multiplication 
definition 135 
operator 7 


N 


names 

of EXECs 47 
of functions 70 
of programs 47 
of subroutines 28 
of variables 4 
negation 

of logical values 9 
of numbers 7 

nesting of control structures 30 
NOP instruction 43 

not equal operator (->=*) 8 
not equal operator (/ =) 8 
not exactly equal operator (i = = ) 8 
not exactly equal operator (/=*) 8 
not greater than operator (-»>) 8 

not less than operator (-»<) 8 

NOT operator 9 

notation 

engineering 141 
scientific 141 

NOTYPING flag cleared before error messages 177 
NOVALUE condition 

on SIGNAL instruction 58 
use of 143 

NUCON holds EXECFLAG byte 164 
null clauses 11 


null instruction 

See NOP instruction 
null strings 3, 6 
numbers 

arithmetic on 7, 133, 135 
checking with DATATYPE 80 
comparison of 8, 139 
definition 134 
description of 4, 133 
formatting for display 85 
in DO instruction 31 
truncating 98 
use in the language 141 
NUMERIC 

instruction 44 

option of PARSE instruction 47, 141 
settings saved during subroutine calls 29 


o 


operation tracing results 62 
operator 

arithmetic 7, 133, 135 
as special characters 4 
comparitive 8, 139 
concatenation 7 
logical 9 

precedence (priorities) of 9 
OPTIONS instruction 45 
OR, logical 
exclusive 9 
inclusive 9 

ORDERED option of DATE function 81 
ORing character strings together 76 
OTHERWISE clause 

See SELECT instruction 
overflow, arithmetic 141 
OVERLAY function 90 
overlaying a string onto another 90 


P 


packing a string with X2C 102 
parameter list 
extended 17 
tokenized 17 
parentheses 

adjacent to blanks 5 
in expressions 6 
in function calls 69 
in parsing templates 128 
PARSE instruction 46 
parsing 123-132 
definition 125 
general rules 123, 126 


Index 
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introduction 123 
literal patterns 126 
multiple strings 131 
patterns 126 
positional patterns 129 
selecting words 127 
variable patterns 128 
parsing templates 

in ARG instruction 26 
in PARSE instruction 46 
in PULL instruction 51 
patterns in parsing 126 
performance considerations 167 
period 

causing substitution in variable names 13 
in numbers 135 

period as placeholder in parsing 129 
permanent command destination change 24 
plist 

extended 153 
for accessing variables 159 
for invoking EXECs 149 
for invoking external routines 157 
POS function 90 
position 

last occurrence of a string 88 
of character using INDEX 86 
powers of ten in numbers 4 
precedence of operators 9 
precision 

precision of arithmetic 135 
presumed command destinations 24 
PROCEDURE instruction 49 
programming restrictions 1 
programming style 143, 167 
programs 

retrieving lines with SOURCELINE 93 
retrieving name of 47 
protecting variables 49 

pseudo random number function of RANDOM 91 
PULL instruction 51 
PULL option of PARSE instruction 47 
pure number 
See numbers 

purging storage resident EXECs 147 
PUSH instruction 52 


Q 


QUERY EXECTRAC command 120 
queue 

counting lines in 91 
reading from with PULL 51 
writing to with PUSH 52 
writing to with QUEUE 53 
QUEUE instruction 53 
QUEUED function 91 


R 


RANDOM function 91 

random number function of RANDOM 91 

RC (return code) 

not set during interactive debug 118 
set by host commands 16 
set to 0 if commands inhibited 64 
special variable 144 
reading CMS files 147 
reading the stack and console 51 
remainder 

definition 136 
description of 133 
operator 7 

reordering data with TRANSLATE function 98 
repeating a string with COPIES 78 
repetitive loops 
altering flow 42 
controlled repetitive loops 33 
exiting 42 
simple do group 32 
simple repetitive loops 32 
request block 

for accessing variables 160 
reservation of keywords 143 
restoring variables 36 
restrictions 

embedded blanks in numbers 4 
first character of variable name 12 
maximum length of results 6 
restrictions in programming 1 
Restructured Extended Executor language (REXX) 
interpreter structure 167 
RESULT 

set by RETURN instruction 29, 54 
special variable 144 
results 

length of 6 

retrieving argument strings with ARG 26 
return codes 

as set by host commands 16 
setting on exit 37 
RETURN instruction 54 
return string 

setting on exit 37 

returning control from REXX program 54 
REVERSE function 92 

REXX (Restructured Extended Executor) language 
interpreter structure 167 
RIGHT function 92 
rounding 

definition 135 

using a character string as a number 4 
routines 

See functions 
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See subroutines 

running off the end of a program 37 
RX prefix on external routines 157 
RXSYSFN description 104 


s 


SAY (REXX instruction) 55 
scientific notation 141 
search order 

for commands 17 
for functions 71 
for subroutines 28 
searching a string for a phrase 85 
seconds calculated from midnight 96 
SELECT instruction 56 
semicolons 
implied 5 
omission of 23 
within a clause 2 
SET EXECTRAC command 

external control of tracing 120 
shift-in (SI) characters 45 
shift-out (SO) characters 45 
SHVBLOCK format 160 
SI (shift-in) characters 45 
SIGL 

set by CALL instruction 29 
set by SIGNAL instruction 60 
special variable 144 
SIGN function 93 
SIGNAL 

execution of in subroutines 29 
in INTERPRET instruction 39, 61 
SIGNAL instruction 58-61 
significant digits in arithmetic 135 
simple number 
See numbers 
simple symbols 13 
single stepping 

See interactive debug 
six-word extended plist 153 
SO (shift-out) characters 45 
SORTED option of DATE function 81 
source of the program and retrieval of 
information 47 

SOURCE option of PARSE instruction 47 
SOURCELINE function 93 
SPACE function 93 
special characters 5 
special variables 
RC 144 
RESULT 144 
SIGL 144 

SPOOL EXEC, avoiding 19 
SPOOL MODULE, avoiding 19 
stack 


counting lines in 91 
reading from with PULL 51 
writing to with PUSH 52 
writing to with QUEUE 53 
stem of a variable 
assignment to 14 
description of 13 
used in DROP instruction 36 
used in PROCEDURE instruction 49 
stepping through programs 
See interactive debug 
storage 

accessing 116 
finding upper limit of 116 
STORAGE function 116 
storage, execution from 153 
string 

as literal constants 3 

as names of functions 3 

as names of subroutines 30 

comparison of 8 

concatenation of 7 

description of 3 

hexadecimal specification of 3 

interpretation of 39 

length of 6 

null 3, 6 

quotes in 3 

verifying contents of 100 
STRIP function 94 
structure and syntax 2 
style of programming 143, 167 
SUBCOM function 21 
subcommand destinations 24 
subcommands 

addressing of 24 
concept 20 
subroutines 

calling of 28 

external interface 157 

forcing built-in or external reference 28 

naming of 30 

passing back values from 54 
return from 54 
use of labels 28 
variables in 49 
substitution 

in expressions 6 
in variable names 13 
SUBSTR function 94 
subtraction 

definition 135 
operator 7 

SUB WORD function 95 
symbol 

assigning values to 12 
classifying 12 
constant 12 
description of 3 
simple 13 
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uppercase translation 3 
use of 12 
valid names 4 
SYMBOL function 95 
syntax checking 

See TRACE instruction 

SYNTAX condition of SIGNAL instruction 58 
syntax error 

traceback after 66 
trapping with SIGNAL instruction 58 
syntax, general 2 
system interfaces 149 
system trace bit 120 


T 


TE (Trace End) immediate command 119 
templates, parsing 
general rules 123 
in ARG instruction 26 
in PARSE instruction 46 
in PULL instruction 51 
temporary command destination change 24 
ten, powers of 140 
terminals 

finding width with LINESIZE 89 
reading from with PULL 51 
writing to with SAY 55 
terms and data 6 
text formatting 
See formatting 
See word 
THEN 

as free standing clause 23 
following IF clause 38 
following WHEN clause 56 
TIME function 96 
TO phrase of DO instruction 31 
tokens, classes of 2 
trace bit, external 120 
Trace End (TE) immediate command 117 
TRACE function 97 
TRACE instruction 62 

See also interactive debug 
TRACE setting 

altering with TRACE function 97 
altering with TRACE instruction 62 
querying 97 

Trace Start (TS) immediate command 117 
trace tags 66 

traceback, on syntax error 66 
tracing 

action saved during subroutine calls 29 


by interactive debug 117 
data identifiers 66 
execution of programs 62 
external control of 119, 120 
looping programs 119 
tracing flags 


4- + + 

66 

*-* 66 

> . > 

66 

> > > 

66 

>c> 

66 

>F> 

66 

>L> 

66 

>0> 

66 

>P> 

66 

>V> 

66 


trailing blank removed using STRIP function 94 
trailing zeros 137 
TRANSLATE function 98 
translation 

See also uppercase translation 
with TRANSLATE function 98 
with UPPER instruction 68 
trapping of conditions 

See SIGNAL instruction 
TRUNC function 98 
truncating numbers 98 
TS (Trace Start) immediate command 119 
type of data checking with DATATYPE 80 
type-ahead line counting with EXTERNALS 85 
typing data 

See SAY (REXX instruction) 


u 


unassigning variables 36 
unconditionally leaving your program 37 
underflow, arithmetic 141 
unpacking a string with C2X 79 
UNTIL phrase of DO instruction 31 
UPPER instruction 68 
UPPER option of PARSE instruction 46 
uppercase translation 

during ARG instruction 26 
during PULL instruction 51 
of symbols 3 
with PARSE UPPER 46 
with TRANSLATE function 98 
with UPPER instruction 68 
USA option of DATE function 81 
USERID function 99 
utility functions 73-103 
function packages 103 
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V 


VALUE function 99 

VALUE option of PARSE instruction 48 

VAR option of PARSE instruction 48 

variable names 4 

variables 

compound 13 

controlling loops 33 

description of 12 

direct interface to 159 

dropping of 36 

exposing to caller 49 

getting value with VALUE 99 

in internal functions 49 

in subroutines 49 

new level of 49 

parsing of 48 

resetting of 36 

setting new value 12 

simple 13 

special 

RC 144 
RESULT 144 
SIGL 144 

testing for initialization 95 
translation to uppercase 68 
valid names 12 
VERIFY function 100 
VERSION option of PARSE instruction 48 
VM/SP unique functions 104 


checking with DATATYPE 80 
description of 4 
word 

counting in a string 101 
deleting from a string 82 
extracting from a string 95, 100 
finding in a string 85 
finding length of 101 
in parsing 127 
locating in a string 101 
WORD function 100 
word processing 
See formatting 
See word 

WORDINDEX function 101 
WORDLENGTH function 101 
WORDS function 101 
writing CMS files 147 
writing to the stack 
with PUSH 52 
with QUEUE 53 


X 


XEDIT macro interface 20 
XOR, logical 9 

XORing character string together 77 
XRANGE function 102 
X2C function 102 
X2D function 102 




WEEKDAY option of DATE function 81 
WHEN clause 

See SELECT instruction 
WHILE phrase of DO instruction 31 
whole numbers 


zeros added on the left 92 

zeros removal with STRIP function 94 


Index 
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